Configuration

This guide provides detailed information on configuring Model Context Protocol (MCP) servers with Kiro, including configuration file structure, server setup, and management across all surfaces.

MCP configuration files use JSON format with the following structure:

{
  "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",
        "HEADER2": "value2"
      },
      "disabled": false,
      "autoApprove": ["tool_name1", "tool_name2"],
      "disabledTools": ["tool_name3"]
    }
  }
}

When multiple configurations define the same MCP server, they are loaded based on this hierarchy (highest to lowest priority):

1. Agent Config - mcpServers field in agent JSON
2. Workspace MCP JSON - .kiro/settings/mcp.json
3. Global MCP JSON - ~/.kiro/settings/mcp.json

Complete override:

Agent config:     { "fetch": { command: "fetch-v2" } }
Workspace config: { "fetch": { command: "fetch-v1" } }
Global config:    { "fetch": { command: "fetch-old" } }

Result: Only "fetch-v2" from agent config is used

Additive (different names):

Agent config:     { "fetch": {...} }
Workspace config: { "git": {...} }
Global config:    { "aws": {...} }

Result: All three servers are used (fetch, git, aws)

Disable via override:

Agent config:     { "fetch": { command: "...", disabled: true } }
Workspace config: { "fetch": { command: "..." } }

Result: No fetch server is launched

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-bravesearch"
      ],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "api-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-Custom-Header": "value"
      }
    }
  }
}

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git"],
      "env": {
        "GIT_CONFIG_GLOBAL": "/dev/null"
      }
    },
    "aws-docs": {
      "command": "npx",
      "args": ["-y", "@aws/aws-documentation-mcp-server"]
    }
  }
}

Many MCP servers require environment variables for authentication or configuration. Use the ${VARIABLE_NAME} syntax to reference environment variables:

{
  "mcpServers": {
    "server-name": {
      "env": {
        "API_KEY": "${YOUR_API_KEY}",
        "DEBUG": "true",
        "TIMEOUT": "30000"
      }
    }
  }
}

Remote MCP servers that require OAuth authentication are supported. Kiro handles the browser-based OAuth flow automatically when connecting to an OAuth-protected server.

{
  "mcpServers": {
    "remote-server-with-oauth": {
      "url": "https://api.example.com/mcp",
      "oauth": {
        "clientId": "your-client-id",
        "redirectUri": "http://127.0.0.1:8080/oauth/callback",
        "oauthScopes": ["read", "write"]
      }
    }
  }
}

If you encounter OAuth scope errors, use an empty array: "oauthScopes": []

Most servers use Dynamic Client Registration (DCR) and need no extra configuration - just connect, and Kiro opens the authorization page.

For servers that don't support Dynamic Client Registration (DCR) - like Figma, Slack, or GitHub - you can provide your own OAuth credentials in the oauth object. This works with auth servers like Cognito, Auth0, and Okta.

{
  "mcpServers": {
    "figma": {
      "url": "https://mcp.figma.com/mcp",
      "oauth": {
        "clientId": "my-figma-client-id",
        "clientSecret": "my-figma-client-secret",
        "redirectUri": "http://localhost:7778/oauth/callback",
        "oauthScopes": ["files:read"]
      }
    }
  }
}

To use this configuration, register an OAuth app in the Figma Developer Console. Set the redirect URI in your app settings to http://localhost:7778/oauth/callback - the port and path must match exactly. Figma requires a confidential client, so both clientId and clientSecret are needed.

• No clientId or clientMetadataUrl set - Kiro attempts Dynamic Client Registration with the server. If DCR fails, it falls back to a default client configuration.
• clientId set (without clientSecret) - Kiro skips DCR and authenticates as a public OAuth client using your registered client ID.
• clientId and clientSecret both set (CLI only) - Kiro skips DCR and authenticates as a confidential client, sending the secret to the token endpoint. This is required for servers like Figma that issue tokens only to confidential clients.
• clientMetadataUrl set (without clientId) - Kiro skips DCR and presents the metadata document URL as its client identity, when the authorization server supports it. See Client ID Metadata Documents below.

If you bring your own identity provider, your MCP server must serve authorization-server metadata at the RFC 8414 well-known URL and validate Bearer tokens against the provider's JWKS. For an issuer without a path such as https://auth.example.com, metadata lives at https://auth.example.com/.well-known/oauth-authorization-server. For a path-bearing issuer such as https://auth.example.com/tenant1, the well-known suffix is inserted before the path, giving https://auth.example.com/.well-known/oauth-authorization-server/tenant1.

The redirectUri field accepts several formats. The host must be 127.0.0.1 or localhost, and the scheme must be http (the callback is served by a local loopback server).

Use a full URL with a custom path when your OAuth app has a pre-registered redirect URI that includes a specific callback path. Whatever you configure is the exact redirect_uri Kiro sends and the only endpoint its local server answers, so register the same value with your provider - including the host spelling, since localhost and 127.0.0.1 are not interchangeable to most authorization servers.

A redirectUri Kiro cannot serve is reported as a configuration error on the server rather than ignored: the port must be present and between 1 and 65535, the host must be 127.0.0.1 or localhost, the scheme must be http, and the value cannot carry a query string or fragment.

If you host a Client ID Metadata Document, set oauth.clientMetadataUrl to its HTTPS URL. Instead of registering a client through DCR, Kiro presents that URL as its client identity, and the authorization server fetches your document to learn the client's metadata. This works only when the authorization server advertises client_id_metadata_document_supported; otherwise Kiro falls back to DCR.

{
  "mcpServers": {
    "enterprise-server": {
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientMetadataUrl": "https://apps.example.com/kiro-client.json",
        "redirectUri": "http://127.0.0.1:8080/oauth/callback"
      }
    }
  }
}

Do not set both clientMetadataUrl and clientId. When a clientId is present, Kiro uses it and never consults clientMetadataUrl.

You can specify OAuth scopes in two places:

{
  "mcpServers": {
    "server": {
      "url": "https://mcp.example.com",
      "oauthScopes": ["openid", "email"],
      "oauth": {
        "clientId": "my-id",
        "oauthScopes": ["read:data", "write:data"]
      }
    }
  }
}

When both are set, oauth.oauthScopes takes priority. When neither is specified, Kiro requests a default set of scopes (openid, email, profile, offline_access).

When an OAuth token expires during a session and no refresh token is available, Kiro automatically triggers a new browser-based authentication flow. You don't need to restart your session - the re-authentication happens transparently and the MCP server reconnects with the new token. In the IDE, a warning indicator and Re-authenticate button appear in the MCP panel when a token expires.

This is particularly useful for identity providers that issue short-lived tokens without refresh tokens.

When automatic refresh isn't sufficient - for example, if a token was revoked or you need to switch accounts - you can manage OAuth credentials manually in the CLI:

Keyboard shortcuts are available in the MCP panel status view. See Slash Commands for full usage details.

Agent and MCP configurations hot-reload when you save changes on disk. A file watcher monitors .kiro/agents directories and mcp.json files, reconciling the running servers and agent state without restarting your session or losing conversation context.

This applies to:

• Editing an existing agent config or mcp.json
• Adding or removing an agent file
• Adding, removing, or editing MCP server entries

How reconciliation works:

• Only changed servers restart - if you add, remove, or edit a server entry, only the affected servers are stopped or started. Unchanged servers continue running.
• Order-independent config diff - reordering environment variables or JSON keys does not count as a change and won't trigger a restart.
• Session-injected servers preserved - servers added mid-session via /mcp add are re-merged during reconciliation.

No command is required to trigger a reload. Save the file and the change takes effect at the next idle boundary (between turns).

To temporarily disable an MCP server without removing its configuration, set disabled to true:

{
  "mcpServers": {
    "server-name": {
      "disabled": true
    }
  }
}

To keep a server active but prevent an agent from using specific tools, use disabledTools:

{
  "mcpServers": {
    "server-name": {
      "disabledTools": ["delete_file", "execute_command"]
    }
  }
}

For enterprise teams using IAM Identity Center, MCP server access can be centrally controlled through an MCP registry. See the MCP Registry page for details.

1. Validate JSON syntax

   • Ensure your JSON is valid with no syntax errors
   • Check for missing commas, quotes, or brackets
   • Use a JSON validator or linter

2. Verify command paths

   • Make sure the command specified exists in your PATH
   • Try running the command directly in your terminal

3. Check environment variables

   • Verify that all required environment variables are set
   • Check for typos in environment variable names

4. OAuth issuer mismatch

   • If an OAuth-protected server fails to connect, the authorization server URL your MCP server advertises may not exactly match the issuer value in the authorization-server metadata.
   • Fetch /.well-known/oauth-protected-resource from your MCP server. Note the URL in authorization_servers[0].
   • Fetch the authorization-server metadata for that issuer URL. Per RFC 8414, for an issuer without a path (e.g. https://auth.example.com) the metadata endpoint is https://auth.example.com/.well-known/oauth-authorization-server; for a path-bearing issuer (e.g. https://auth.example.com/tenant1) it is https://auth.example.com/.well-known/oauth-authorization-server/tenant1. Compare the returned issuer field against authorization_servers[0] character-for-character: scheme, host, port, path, and trailing slash must be identical. For example, https://auth.example.com and https://auth.example.com/ are treated as different issuers.
   • Correct whichever metadata source has the wrong value. Do not add client-side normalization or bypasses.

5. Pass arguments to Kiro CLI V2 stdio servers on Windows

   • In Kiro CLI V2 sessions, arguments pass unchanged when a command resolves on PATH to an .exe, .com, .bat, or .cmd file.
   • Other commands, and servers whose env sets PATHEXT, still launch through cmd.exe.
   • Directly resolved servers do not run the cmd.exe AutoRun hook. If AutoRun sets PATH, add that value to the server's env configuration instead.
   • An argument containing a line break causes a .bat or .cmd launch to fail instead of truncating the argument.

6. Review configuration loading

   • Check which configuration files are being loaded and their priority:
   bash

   # Check workspace config
   cat .kiro/settings/mcp.json
   
   # Check user config
   cat ~/.kiro/settings/mcp.json
   

When configuring MCP servers, follow these security best practices:

• Use environment variable references (e.g., ${API_TOKEN}) instead of hardcoding sensitive values
• Never commit configuration files with credentials to version control
• Only connect to trusted remote servers
• Review tool permissions before adding them to autoApprove
• Use disabledTools to restrict access to dangerous operations

For comprehensive security guidance, see the MCP Security Best Practices page.