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 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.

If you bring your own identity provider, your MCP server must serve a /.well-known/oauth-authorization-server metadata document pointing to the provider's endpoints, and validate Bearer tokens against the provider's JWKS.

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.

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. 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.