How to Add a Remote MCP Server to Kiro

How do I add a remote MCP server to Kiro?

Add the server's URL to ~/.kiro/settings/mcp.json (or .kiro/settings/mcp.json for a single project), or use the MCP servers tab in the Kiro panel. The URL is the entire configuration — no tokens, headers, or client IDs — and Kiro runs the browser authorization on its own the first time it connects. Save the file and you are done: Kiro watches these files and hot-reloads the server without restarting your session or losing conversation context.

Kiro is AWS's agentic IDE. Nothing in Kiro's plans or pricing gates MCP — the tiers differ on credits and model access, not on this — so the free tier connects the same way the paid tiers do. There are two real gates, and neither is your plan:

• Surface. Remote MCP servers work in the Kiro IDE and the Kiro CLI. Kiro Web and Kiro Mobile don't support remote MCP servers or the JSON config file at all.
• Enterprise policy. An administrator can disable MCP outright or restrict you to a vetted list of servers. When that's in play, Kiro says so directly: "MCP has been disabled by your administrator."

Choose where to configure it

Kiro reads MCP servers from two files, and knowing which is which saves a genuinely baffling debugging session:

• Workspace: .kiro/settings/mcp.json — applies to the current project only
• User: ~/.kiro/settings/mcp.json — applies everywhere

The files merge, so servers defined in different places all load. On a name collision, the higher scope replaces the lower entry outright — it is not a field-by-field merge, so a partial workspace entry won't inherit anything from the user file. The full order, highest first:

1. Agent config — the mcpServers field inside a custom agent's JSON
2. Workspace — .kiro/settings/mcp.json
3. User — ~/.kiro/settings/mcp.json

That hierarchy is behind most "I definitely fixed this URL" reports — the fix landed in the user file while a stale copy higher up kept taking precedence. If you use custom agents, check the agent config first: it outranks both files, and agents also carry an includeMcpJson setting that decides whether mcp.json is read at all.

For a server that belongs to you rather than to a project, user scope is usually what you want.

The Kiro panel has an MCP Servers tab, which is where you confirm and manage connections. Note it is not a form-based alternative to the config file: clicking + there, like the Open MCP Config icon, opens mcp.json for you to edit.

The config

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

That is all of it. Kiro infers the rest.

Authorization

After you save, a popup appears in the lower-right corner asking you to authenticate the server. Click authenticate and allow Kiro to open the external website — a browser tab opens with the server's consent screen, where you sign in and approve. Kiro handles the OAuth handshake itself, attempting dynamic client registration when no clientId is set and falling back to a default client configuration if that fails, so there is normally nothing to paste. Token refresh during a session happens transparently, without restarting anything.

To verify, ask in a Kiro chat what tools it has access to. If the server's tools are listed, you are connected.

What usually goes wrong

• Tools not appearing in chat. Don't reach for a restart — Kiro hot-reloads on save. But the reload lands at the next idle boundary, between turns, so a change saved mid-turn won't take effect until the current turn finishes. If it still hasn't appeared: check that MCP support is enabled in Settings, that the JSON parses, and that the same server isn't defined at a higher scope holding an older URL.
• Configured but not connecting. Check whether the server is defined more than once — an agent config outranks the workspace file, which outranks the user file, and the winning entry replaces the others whole.
• Connection fails immediately. Check the URL against exactly what the server publishes, including the path and any trailing slash.
• The browser never opens for authorization. Look for the authenticate popup in the lower-right corner first — that click is what opens the browser. If you dismissed it, re-save the config to trigger it again, then check pop-up blockers and that a default browser is set at the OS level.
• "MCP has been disabled by your administrator." Enterprise policy, not a config problem. Your admin has either turned MCP off or restricted it to an allowed list.
• Wondering whether the free tier is the problem. It isn't — Kiro's tiers differ on credits and models, not MCP. Check the surface instead: remote MCP servers are an IDE and CLI feature, not a Kiro Web or Mobile one.

A worked example

With a real server — Tempreon, a hosted MCP server that gives your AI a persistent memory of how you work:

{
  "mcpServers": {
    "tempreon": {
      "url": "https://api.tempreon.com/functions/v1/tempreon-mcp/mcp"
    }
  }
}

Two things make Kiro a useful place to connect a server like this. Its model lineup spans open-weight models — Qwen3 Coder Next, DeepSeek 3.2, MiniMax M2.1 — alongside Claude and GPT models, and because MCP lives in the harness rather than the model, every one of them reaches the server through the same connection. And the Kiro CLI carries over the IDE's MCP configuration, so connecting once in the IDE makes the server available in your terminal sessions too.

The account-holder walkthrough, including a one-click install link, is in the Kiro setup doc.