Add an MCP Server

MCP is the protocol Kiro uses to reach external tools and data. You add a server by describing how to start it, or where to reach it, in a small JSON file.

When to use this

Add an MCP server when the agent needs something outside your repository: a documentation search, an issue tracker, a database, a design tool. If a Power already bundles the server you want, install the Power instead. It carries the same MCP configuration plus instructions on when to use it.

Steps

1. Decide the scope. Team-wide servers belong in the workspace file so everybody gets them. Personal servers belong in your global file.

2. Create the file for that scope. Workspace: .kiro/settings/mcp.json. Global: ~/.kiro/settings/mcp.json.

3. Add a local server under mcpServers. Use command, args, and env. Environment variables expand with ${VAR} syntax, so no secret is written into the file.

   .kiro/settings/mcp.json

   {
     "mcpServers": {
       "docs-search": {
         "command": "npx",
         "args": ["-y", "example-docs-mcp-server"],
         "env": { "DOCS_TOKEN": "${DOCS_TOKEN}" },
         "autoApprove": [],
         "disabled": false
       }
     }
   }

4. Add a remote server with url instead of command, plus headers or oauth for authentication. In the CLI, /mcp auth starts the sign-in, /mcp cancel-auth cancels a pending one, and /mcp logout clears saved credentials.

5. Leave autoApprove as an empty list. Work for a week, watch which tools the server actually uses, then add those specific names. "autoApprove": "*" exists and approves everything, including tools the server adds later.

6. Mask anything you do not want available with disabledTools, or turn the whole server off with "disabled": true.

7. Save the file. The CLI hot-reloads agent and MCP settings on save since v2.10.0, so you keep your session and its history.

8. For headless or CI runs, add --require-mcp-startup to the command so the job fails immediately when a server cannot connect.

Check it worked

In the IDE, open the MCP servers panel and confirm the server shows as connected. In the CLI (v2.21.0 and later), the configuration panel lists MCP servers next to agents, Powers, steering, skills, and hooks. Then ask the agent to do something only that server can do, and watch for the approval prompt on the first call.

Common problems

• The server never connects. Run the command and args yourself in a terminal. Most failures are a missing runtime or a package name typo.
• An environment variable is empty. ${VAR} expands from your environment, not from the repository. Export it in your shell profile or your CI secret store.
• Approval prompts on every call. That is the default and it is correct. Add the read-only tool names to autoApprove once you know them.
• Two servers with the same name. The closest scope wins: agent, then project, then global. Rename one if you meant to run both.
• A pipeline hangs. Add --require-mcp-startup. Without it a headless run can wait on a server that will never answer.
• You need logs. The IDE writes to the “Kiro - MCP Logs” output channel.

Related

• MCP explains the protocol and the configuration keys.
• Add a Power bundles MCP config with instructions.
• Set up permissions.yaml controls the mcp capability.