Kiro MCP server not connecting, or not loading: the fixes

Turn MCP on and find the file that wins

In the IDE, open Settings (Cmd+, on macOS, Ctrl+, elsewhere), search for MCP and enable MCP support. Then check where the server is defined. Kiro loads, from highest priority to lowest:

1. The mcpServers field of an agent config.
2. The workspace file, .kiro/settings/mcp.json.
3. The user file, ~/.kiro/settings/mcp.json.

Servers with different names are combined. A name defined in two places uses the higher definition in full, with nothing merged from the lower one, and "disabled": true in a higher source stops the server even if a lower one enables it. So an edit to ~/.kiro/settings/mcp.json does nothing while the workspace file has a server of the same name. cat both files to see what Kiro loads.

{
  "mcpServers": {
    "my-local": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": { "API_KEY": "${MY_API_KEY}" }
    },
    "my-remote": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${MY_TOKEN}" },
      "autoApprove": ["read_items"]
    }
  }
}

Saved changes apply between turns

Saving the file applies it: Kiro reconnects and restarts only the servers that changed. The change lands at the next idle point between turns, so a reply already in progress still uses the old setup. Wait for it to finish before testing again.

Variables that don't expand

• Kiro expands ${VARIABLE_NAME} only for variables you've approved. In the IDE that list is the Mcp Approved Env Vars setting; a config that uses an unapproved variable brings up a security warning naming it.
• An unexpanded variable reaches the server as literal text, so a header of Bearer ${MY_TOKEN} is rejected as a bad token. Add the name to the approved list rather than pasting the secret into the file.
• The variable also has to be set in the environment Kiro started with. Set it in your shell profile, then quit and reopen Kiro.

OAuth sign-in fails

• Most remote servers register Kiro themselves (Dynamic Client Registration) and need no oauth block. For a server without it, set oauth.clientId; oauth.clientSecret works in the CLI only.
• A custom oauth.redirectUri must be http on 127.0.0.1 or localhost, with no query string or fragment.
• Kiro aborts discovery when the issuer doesn't match exactly. Fetch the server's /.well-known/oauth-protected-resource, then compare authorization_servers[0] with the issuer in the authorization server's metadata character by character: a trailing slash on one and not the other is enough.
• When a token expires, the IDE's MCP panel shows Re-authenticate. In the CLI, /mcp auth forces a new sign-in, /mcp cancel-auth stops a stuck one and /mcp logout removes stored credentials.

Local servers that won't start

• Check the JSON first: a missing comma, quote or bracket breaks the file.
• Run the command and args in a terminal. If the command isn't on your PATH there, Kiro can't find it either.
• On Windows in the CLI, commands that resolve to .exe, .com, .bat or .cmd get their arguments unchanged; other commands, and servers whose env sets PATHEXT, start through cmd.exe. An argument with a line break makes a .bat or .cmd launch fail.

Taskhold-specific checks

Taskhold is a remote server at https://taskhold.com/api/mcp with standard OAuth discovery: authorization_servers[0] and the issuer are both https://taskhold.com, and it supports Dynamic Client Registration. When its tools don't show up in Kiro, check these in order:

1. The entry has url set to exactly https://taskhold.com/api/mcp and no headers. Kiro then signs in over OAuth, with no sign-up first: the first time Kiro uses Taskhold it gives you the link to start the 7-day trial.
2. No same-named taskhold entry in a higher-priority file (the workspace file or an agent config) with old headers or disabled set.
3. If you use an atd_sk_ key instead, TASKHOLD_API_KEY is on Mcp Approved Env Vars. Taskhold's 401 names the cause: bad_header usually means the variable reached it unexpanded.
4. Ask Kiro to call the taskhold list tool. Settings in Taskhold shows the connection once the first call arrives.

With the tools loaded and the workflow from the Kiro page in AGENTS.md or a steering file, every task Kiro starts, its steps and its questions show on the live board next to your other agents. The same checks for other clients: Cursor, Zed and Cline.