Configuration

MCP servers are configured through JSON files at the workspace or user level. Start with a basic server entry, then layer in environment variables, OAuth, or priority overrides as your setup grows.

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,
      "disabledTools": ["tool_name3"]
    },
    "remote-server-name": {
      "url": "https://endpoint.to.connect.to",
      "headers": {
        "HEADER1": "value1",
        "HEADER2": "value2"
      },
      "disabled": false,
      "disabledTools": ["tool_name3"]
    }
  }
}

{
  "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"]
    }
  }
}

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

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"
      }
    }
  }
}

Make sure to set these environment variables in your shell before running Kiro CLI:

export YOUR_API_KEY="your-actual-key"
export DEBUG="true"

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"]
    }
  }
}

Agent and MCP configurations now 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).

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

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:

{
  "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 — 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.

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

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:

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

To verify your configuration, check which MCP servers are currently loaded in an interactive chat session:

/mcp

This displays all active MCP servers, their connection status, and available tools. If a server you configured doesn't appear in the list, check the troubleshooting section below — the most common causes are JSON syntax errors and missing environment variables.

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
• Use disabledTools to restrict access to dangerous operations

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