Add a Remote MCP Server to Kiro (mcp.json)

Kiro takes a remote MCP server as one entry with a url in an mcp.json file [1]:

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Put it in ~/.kiro/settings/mcp.json to have the server in every workspace, or in .kiro/settings/mcp.json inside a project for that workspace only [1]. You can open either from the command palette: Kiro: Open user MCP config (JSON) or Kiro: Open workspace MCP config (JSON) [2]. Changes apply when you save the file [1].

Everything below is checked against Kiro's MCP documentation on 26 October 2026 [1][2].

TL;DR:

• url is the only required field for a remote server, and it must be HTTPS. Plain HTTP is accepted only for localhost [1].
• A token in ${VAR} needs approving first. Kiro only expands environment variables you have added to the Mcp Approved Env Vars setting [1].
• OAuth runs on its own. Kiro opens the browser sign-in itself, and most servers need no extra configuration [1].
• The workspace file wins over the user file when both name the same server [1].

Which file wins

Kiro merges three places, highest priority first [1]:

When the same server name appears in more than one, the higher one is used [1]. That is also how to switch a user-wide server off for one project: define it again in the workspace file with "disabled": true [1].

Add the server

The entry at the top is the whole configuration for an open server. Save the file and Kiro picks it up at the next pause between turns, restarting only the servers you added, removed or edited [1].

The URL is the MCP endpoint itself, usually ending in /mcp, not the product's homepage or its docs page.

Kiro also accepts one-click install links using the kiro:// scheme. Before installing, it shows a dialog with the server's details, with header and environment values hidden, and its docs say to install only from sources you trust [2].

Keep the token out of the file

A server that takes an API key gets a headers object, and the key can come from an environment variable with ${VARIABLE_NAME} [1]:

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MY_SERVER_TOKEN}"
      }
    }
  }
}

Kiro only expands environment variables that are explicitly approved [1]. Open Kiro's settings, search for Mcp Approved Env Vars, and add MY_SERVER_TOKEN there [1]. Skip that step and the header does not carry your key, which the server answers with a 401.

Sign in to a server that needs it

Kiro handles the browser-based OAuth sign-in itself when it connects to a server that asks for one, and most servers use Dynamic Client Registration and need nothing extra in the file [1]. We read the authorization metadata of 169 servers that ask for credentials, from our registry census on 9 October 2026: 162 offered Dynamic Client Registration [3].

For a server that only accepts a pre-registered client, add its client ID, and Kiro skips registration [1]:

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "your-client-id"
      }
    }
  }
}

The Kiro IDE supports public OAuth clients only, so a client secret is not used there; the Kiro CLI also accepts oauth.clientSecret [1]. If the server's sign-in only allows a fixed callback address, oauth.redirectUri pins it, and it must be on localhost or 127.0.0.1 over http [1].

Kiro compares the authorization server's issuer exactly, with no normalising, so https://auth.example.com and https://auth.example.com/ count as different issuers [1]. A server whose metadata and issuer disagree by a trailing slash can fail to sign in here even where a more lenient client succeeds. MCP OAuth covers what a server has to publish for the sign-in to work.

Choose which tools run without asking

Two lists on the server's entry control its tools [1]:

• autoApprove: tool names Kiro runs without prompting you. "*" approves every tool on that server.
• disabledTools: tool names Kiro leaves out when it calls the agent.

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp",
      "autoApprove": ["search"],
      "disabledTools": ["delete_record"]
    }
  }
}

When it will not connect

Kiro writes its MCP logs to the Output tab of the Kiro panel, under Kiro - MCP Logs [2]. Start there, then match what you see:

For what the server's own error codes mean, see MCP server errors and MCP server connection failed.

Check it from outside before you share it

Kiro connects from your own machine, so a server on localhost or your VPN works for you and for nobody else. Our MCP connection test calls your server from our network, runs the handshake and tools/list, and reports what a stranger on the internet gets back, with a dated URL you can share. If it passes there and fails in Kiro, the problem is in your mcp.json, not the server.

The same setup in other clients is in Cursor, VS Code, Cline, Windsurf, LM Studio, Claude Code, Codex, Gemini CLI, GitHub Copilot CLI, Claude Desktop and ChatGPT, and remote MCP server vs stdio covers whether your server should have a public address at all.

Sources

1. MCP configuration, Kiro docs
2. MCP, Kiro docs
3. Dynamic Client Registration, MCP Hunter glossary