Kiro and Amazon Q Developer MCP Setup: mcp.json Paths, kiro-cli and Migration

Kiro, AWS's agentic IDE and CLI, reads MCP servers from mcp.json files: .kiro/settings/mcp.json in a workspace and ~/.kiro/settings/mcp.json for your user. If you used Amazon Q Developer CLI, Kiro CLI is its successor. Kiro's docs say it copies your old ~/.aws/amazonq/mcp.json into ~/.kiro/settings/mcp.json during a one-time migration, and still reads project .amazonq folders.

This guide shows the paths, the config format, the kiro-cli mcp add command and what to check after moving from Amazon Q Developer.

Checked against: Kiro's MCP configuration docs, Upgrading from Amazon Q Developer CLI guide and Migrating from Amazon Q Developer guide on 2 November 2026. eSEOspace did not test Kiro.

Amazon Q Developer and Kiro: what changed

Kiro's upgrade guide says "Kiro CLI is the next update of the Q CLI." It became available on 17 November 2025, and installs with auto-update turned on were moved to Kiro CLI on 24 November 2025. Others can switch with q update. The q and q chat commands still work, but Kiro recommends kiro-cli.

Kiro also says you can keep using Amazon Q Developer CLI, but "new features and fixes will only be available for Kiro CLI." For IDE users, Kiro's migration page says everything from Q Developer's IDE extensions, including MCP, is available in Kiro, and that Kiro has no native plugins for Visual Studio or Eclipse.

Where the MCP config lives

This table follows Kiro's upgrade guide. During installation, Kiro CLI copies the user MCP file across, skipping any servers that conflict. It does "not modify" your existing .amazonq folders, and it keeps reading a project's .amazonq folder. If both .kiro and .amazonq exist in a project, Kiro reads .kiro.

Config format

Kiro's docs give this structure, checked on 2 November 2026:

{
  "mcpServers": {
    "local-server-name": {
      "command": "command-to-run-server",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "hard-coded-variable",
        "ENV_VAR2": "${EXPANDED_VARIABLE}"
      },
      "disabled": false,
      "autoApprove": ["tool_name1", "tool_name2"],
      "disabledTools": ["tool_name3"]
    },
    "remote-server-name": {
      "url": "https://endpoint.to.connect.to",
      "headers": {
        "HEADER1": "value1"
      },
      "disabled": false,
      "autoApprove": [],
      "disabledTools": []
    }
  }
}

Key fields:

• command, args, env for local servers; url and headers for remote ones.
• Remote url must be HTTPS, or HTTP for localhost only.
• autoApprove lists tools that run without a prompt. Kiro accepts "*" to auto-approve everything, which we would avoid.
• disabledTools hides tools from the agent.
• oauth and oauthScopes configure sign-in for remote servers.

Use ${VARIABLE} references for keys so the file holds no secrets. The free MCP config generator produces the base mcpServers block.

Set up in Kiro IDE

1. Open Settings (Cmd+, on Mac, Ctrl+, on Windows and Linux), search for "MCP" and enable MCP support.
2. Open the Command Palette and run Kiro: Open workspace MCP config (JSON) or Kiro: Open user MCP config (JSON). You can also use the Open MCP Config icon in the Kiro panel.
3. Add your server and save. Kiro's docs say servers reconnect when you save; no restart needed.

Set up in Kiro CLI

Add a server from the terminal. Kiro's example:

kiro-cli mcp add \
  --name "awslabs.aws-documentation-mcp-server" \
  --scope global \
  --command "uvx" \
  --args "awslabs.aws-documentation-mcp-server@latest" \
  --env "FASTMCP_LOG_LEVEL=ERROR"

To grant a server to one custom agent only, use kiro-cli mcp add --name git-server --agent rust-dev.

Then, in an interactive chat, run /mcp. Kiro says it "displays all active MCP servers, their connection status, and available tools." Kiro's upgrade guide says CLI logs are written to $TMPDIR/kiro-log.

OAuth differences between IDE and CLI

Kiro's docs warn that client-secret support "differs by surface." The CLI supports confidential clients with clientId and clientSecret, which servers such as Figma need. The IDE supports public OAuth clients only, so "services that require a client_secret won't work from the IDE with this configuration."

Kiro Web and team repositories

Kiro also runs in the browser. Its docs say Kiro Web "loads local MCP servers from .kiro/settings/mcp.json in your repository," and you can edit that file or use the Kiro Web settings panel. Some organization-managed sign-ins hide that panel, but editing the repository file "works on every account."

That makes the workspace file the natural place for team servers. Commit .kiro/settings/mcp.json with ${VARIABLE} references instead of real keys, and let each environment supply its own values. Kiro says environment variables and secrets are resolved when the sandbox starts. Review the file in pull requests like any other code, because a new entry can give the agent new tools.

Common mistakes

• Editing ~/.aws/amazonq/mcp.json after migrating. Kiro copied it once; edit ~/.kiro/settings/mcp.json now.
• "autoApprove": ["*"]. It removes every confirmation for that server.
• MCP support switched off in the IDE. Enable it in Settings first.
• JSON syntax errors or missing environment variables. Kiro's docs call these "the most common causes" of a server missing from /mcp.

Next step

Browse AWS servers in our AWS MCP server profile, and compare agents in best AI coding agents with MCP. The MCP tool permission planner helps decide what belongs in autoApprove.

Frequently asked questions