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"] } } }
| Property | Type | Required | Description |
|---|---|---|---|
command | String | Yes | The command to run the MCP server |
args | Array | No | Arguments to pass to the command |
env | Object | No | Environment variables for the server process |
disabled | Boolean | No | Whether the server is disabled (default: false) |
autoApprove | Array | No | Tool names to auto-approve without prompting (use "*" to auto-approve all tools) |
disabledTools | Array | No | Tool names to omit when calling the Agent |
| Property | Type | Required | Description |
|---|---|---|---|
url | String | Yes | HTTPS endpoint for the remote MCP server (or HTTP endpoint for localhost) |
headers | Object | No | Headers to pass to the MCP server during connection |
env | Object | No | Environment variables for the server process |
oauth | Object | No | OAuth configuration for servers that require authentication (see OAuth configuration) |
oauthScopes | Array | No | OAuth scopes to request. See Scopes for which value Kiro uses when oauth.oauthScopes is also set |
disabled | Boolean | No | Whether the server is disabled (default: false) |
autoApprove | Array | No | Tool names to auto-approve without prompting (use "*" to auto-approve all tools) |
disabledTools | Array | No | Tool names to omit when calling the Agent |
In Kiro CLI, both server types also accept timeout, the connection timeout in milliseconds; see the agent configuration reference. Kiro CLI V2 sessions also accept the spelling timeoutMs. In Kiro CLI 3.4.0 or later, V3 sessions accept timeoutMs too; when both are set, timeout wins and timeoutMs has no effect. To confirm the value applies, set "timeoutMs": 1 on a slow local server in a V3 session; /mcp shows that it failed to start within the timeout.
You can configure MCP servers at two levels:
-
Workspace Level:
.kiro/settings/mcp.json- Applies only to the current workspace
- Ideal for project-specific MCP servers
-
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.
Using the command palette:
- Open the command palette (
Cmd + Shift + Pon Mac,Ctrl + Shift + Pon Windows/Linux) - 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
Using the Kiro panel:
- Open the Kiro panel
- Select the Open MCP Config icon
- Open Settings with
Cmd + ,(Mac) orCtrl + ,(Windows/Linux) - Search for "MCP"
- Enable the MCP support setting
Changes to MCP configuration apply automatically when you save the file. Save the config file (Cmd+S) and servers will reconnect.
When multiple configurations define the same MCP server, they are loaded based on this hierarchy (highest to lowest priority):
- Agent Config -
mcpServersfield in agent JSON - Workspace MCP JSON -
.kiro/settings/mcp.json - 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" } } } }
For security, Kiro only expands environment variables that are explicitly approved. When you add or modify an MCP server configuration that includes unapproved environment variables, Kiro displays a security warning popup listing the variables that need approval.
To manage approved environment variables:
- Open Kiro settings
- Search for "Mcp Approved Env Vars"
- Add the environment variables you want to allow for expansion
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.
| Property | Type | Required | Description |
|---|---|---|---|
oauth.clientId | String | No | Pre-registered OAuth client ID. When set, Dynamic Client Registration is skipped entirely. |
oauth.clientSecret | String | No | Client secret for servers that require one. Only meaningful alongside clientId. |
oauth.redirectUri | String | No | Custom loopback redirect URI for the OAuth callback. See redirect URI formats below. |
oauth.clientMetadataUrl | String | No | HTTPS URL of a hosted Client ID Metadata Document. When set, Kiro authenticates as that URL instead of registering a client. See Client ID Metadata Documents below. |
oauth.oauthScopes | Array | No | OAuth scopes to request from the authorization server. See Scopes for which value Kiro uses when top-level oauthScopes is also set. |
- No
clientIdorclientMetadataUrlset - Kiro attempts Dynamic Client Registration with the server. If DCR fails, it falls back to a default client configuration. In Kiro CLI 3.2.0 or later and Kiro IDE 1.4.178 or later, when the authorization server supports Client ID Metadata Documents and offers no registration endpoint, Kiro signs in with its own hosted document instead. See Client ID Metadata Documents below. clientIdset (withoutclientSecret) - Kiro skips DCR and authenticates as a public OAuth client using your registered client ID.clientIdandclientSecretboth 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.clientMetadataUrlset (withoutclientId) - 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).
| Format | Example | Description |
|---|---|---|
| Full URL | http://localhost:7778/oauth/callback | Pin the port and path to match a pre-registered app |
| Host and port | 127.0.0.1:7778 | Pin the port; path defaults to /oauth/callback |
| Port only | :7778 | Pin the port on 127.0.0.1; path defaults to /oauth/callback |
| Omitted | (not set) | OS assigns a random available port on localhost, with the path /oauth/callback |
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.
In Kiro CLI 3.2.0 or later and Kiro IDE 1.4.178 or later, you need no oauth block for a server whose authorization server supports Client ID Metadata Documents and offers no registration endpoint, such as Tableau's hosted MCP. Kiro signs in with its own hosted document, https://kiro.dev/oauth/client-metadata.json, whose redirect URIs are http://localhost/oauth/callback and http://127.0.0.1/oauth/callback with no port. This works only when the authorization server accepts any port on a localhost callback. A server that matches ports exactly rejects the random port Kiro's callback uses. A server that offers Dynamic Client Registration keeps using it, and a configured clientId or clientMetadataUrl still takes priority.
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"] } } } }
Which value Kiro uses when both are set depends on the harness. In Kiro CLI V2 sessions, oauth.oauthScopes takes priority. In Kiro CLI V3 sessions, in Kiro CLI 3.4.0 or later, top-level oauthScopes takes priority, and Kiro reads oauth.oauthScopes, then oauth.scopes, only when top-level oauthScopes is not set; before 3.4.0, V3 ignored the nested value. To request the same scopes on both harnesses, set only one of the two. To confirm which value applied, connect the server and check the scope parameter in the authorization URL Kiro opens. 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:
| Command | Keyboard shortcut | Description |
|---|---|---|
/mcp auth | ^A | Force re-authentication when a token is expired or invalid |
/mcp cancel-auth | ^X | Abort a pending auth flow stuck waiting for browser confirmation |
/mcp logout | ^R | Remove stored credentials for a server |
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 addare 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.
-
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
-
Verify command paths
- Make sure the command specified exists in your PATH
- Try running the command directly in your terminal
-
Check environment variables
- Verify that all required environment variables are set
- Check for typos in environment variable names
-
OAuth issuer mismatch
- If an OAuth-protected server fails to connect, the authorization server URL your MCP server advertises may not exactly match the
issuervalue in the authorization-server metadata. - Fetch
/.well-known/oauth-protected-resourcefrom your MCP server. Note the URL inauthorization_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 ishttps://auth.example.com/.well-known/oauth-authorization-server; for a path-bearing issuer (e.g.https://auth.example.com/tenant1) it ishttps://auth.example.com/.well-known/oauth-authorization-server/tenant1. Compare the returnedissuerfield againstauthorization_servers[0]character-for-character: scheme, host, port, path, and trailing slash must be identical. For example,https://auth.example.comandhttps://auth.example.com/are treated as different issuers. - Correct whichever metadata source has the wrong value. Do not add client-side normalization or bypasses.
- If an OAuth-protected server fails to connect, the authorization server URL your MCP server advertises may not exactly match the
-
Pass arguments to Kiro CLI V2 stdio servers on Windows
- In Kiro CLI V2 sessions, arguments pass unchanged when a command resolves on
PATHto an.exe,.com,.bat, or.cmdfile. - Other commands, and servers whose
envsetsPATHEXT, still launch throughcmd.exe. - Directly resolved servers do not run the
cmd.exeAutoRun hook. If AutoRun setsPATH, add that value to the server'senvconfiguration instead. - An argument containing a line break causes a
.bator.cmdlaunch to fail instead of truncating the argument.
- In Kiro CLI V2 sessions, arguments pass unchanged when a command resolves on
-
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
disabledToolsto restrict access to dangerous operations
For comprehensive security guidance, see the MCP Security Best Practices page.
Configuration