Configuration

Kiro connects to MCP servers through JSON configuration files stored in your workspace or home directory. This page covers the configuration format, where to place config files, and how to set up authentication for remote servers.

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"
      },
      "oauth": {
        "clientId": "your-app-client-id"
      },
      "oauthScopes": ["scope1", "scope2"],
      "disabled": false,
      "autoApprove": ["tool_name1", "tool_name2"],
      "disabledTools": ["tool_name3"]
    }
  }
}

You can configure MCP servers at two levels:

1. Workspace Level: .kiro/settings/mcp.json

   • Applies only to the current workspace
   • Ideal for project-specific MCP servers

2. User Level: ~/.kiro/settings/mcp.json

   • Applies globally across all workspaces
   • Best for MCP servers you use frequently

If both files exist, configurations are merged with workspace settings taking precedence.

1. Open the command palette:

   • Mac: Cmd + Shift + P
   • Windows/Linux: Ctrl + Shift + P

2. Search for "MCP" and select one of these options:

   • Kiro: Open workspace MCP config (JSON) - For workspace-level configuration
   • Kiro: Open user MCP config (JSON) - For user-level configuration

1. Open the Kiro panel
2. Select the Open MCP Config icon

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

Many MCP servers require environment variables for authentication or configuration:

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

To temporarily disable an MCP server without removing its configuration:

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

Kiro handles browser-based OAuth flows automatically when you connect to a remote server that requires it. Most servers use Dynamic Client Registration (DCR) and need no extra configuration — just connect, and Kiro opens the authorization page.

If your server doesn't support DCR, you need to provide your own client ID. Add oauth.clientId to your MCP config along with any required scopes:

{
  "mcpServers": {
    "github": {
      "url": "https://api.github.com/mcp",
      "oauth": {
        "clientId": "your-github-app-client-id"
      },
      "oauthScopes": ["repo", "user"]
    }
  }
}

The following properties control OAuth behavior (see the full property reference above):

• oauth.clientId — Skips DCR. Required when your provider doesn't support dynamic registration.
• oauth.redirectUri — Host and port for the local OAuth callback listener (e.g., "127.0.0.1:8080"). Kiro constructs the full redirect URI from this value. If omitted, a random available port is used.
• oauthScopes — Scopes to request during authorization (e.g., ["search:read", "channels:read"]). This is a top-level property, not nested under oauth.

Some services don't support Dynamic Client Registration (DCR) and require you to register an OAuth app manually through their developer portal. Set oauth.clientId to the client ID from your registered app so Kiro can authenticate without running a separate proxy.

This works with auth servers like Cognito, Auth0, and Okta — as long as the app is configured as a public client using PKCE (no client secret).

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3100/mcp",
      "oauth": {
        "clientId": "your-cognito-app-client-id",
        "redirectUri": "127.0.0.1:8080"
      },
      "oauthScopes": ["openid", "email", "profile"]
    }
  }
}

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

The JSON shape is the same for all services — only url, clientId, and oauthScopes change:

When an OAuth access token expires during a session and no refresh token is available, Kiro detects the expiry and automatically triggers a new browser-based authentication flow. A warning indicator and Re-authenticate button appear in the MCP panel when a token expires.

If you encounter OAuth scope-related errors, configure an empty array to bypass scope requirements:

{
  "mcpServers": {
    "github": {
      "url": "https://api.github.com/mcp",
      "oauthScopes": []
    }
  }
}

When configuring MCP servers, follow security best practices to protect your credentials and system:

• 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

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

If your MCP configuration isn't working:

1. Validate JSON syntax:

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

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. Save configuration changes:

   • Changes to MCP configuration apply automatically when you save the file
   • Simply save the config file (Cmd+S) and servers will reconnect