Configuration

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

Copied!Configuration File Structure

MCP configuration files use JSON format with the following structure:

json

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run-server",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "disabled": false,
      "autoApprove": ["tool_name1", "tool_name2"]
    }
  }
}

Copied!Configuration Properties

Property	Type	Required	Description
`command`	String	Yes	The command to run the MCP server
`args`	Array	Yes	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

Copied!Configuration Locations

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.

Copied!Creating Configuration Files

Copied!Using the Command Palette

Open the command palette:
- Mac: Cmd + Shift + P
- Windows/Linux: Ctrl + Shift + P
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

Copied!Using the Kiro Panel

Open the Kiro panel
Select the Open MCP Config icon

json

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

Copied!Environment Variables

Many MCP servers require environment variables for authentication or configuration:

json

{
  "mcpServers": {
    "server-name": {
      "env": {
        "API_KEY": "your-api-key",
        "DEBUG": "true",
        "TIMEOUT": "30000"
      }
    }
  }
}

Copied!Disabling Servers Temporarily

To temporarily disable an MCP server without removing its configuration:

json

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

Copied!Security Best Practices

When configuring MCP servers:

Don't commit configuration files with sensitive tokens to version control
Use environment variables for sensitive information when possible
Review tool permissions before adding them to autoApprove
Use workspace-level configs for project-specific servers
Regularly rotate API keys and tokens used in configurations

Copied!Troubleshooting Configuration Issues

If your MCP configuration isn't working:

Validate JSON syntax:
- Ensure your JSON is valid with no syntax errors
- Check for missing commas, quotes, or brackets
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
Restart Kiro:
- Changes to MCP configuration require a restart
- Close and reopen Kiro to apply changes

Page updated: July 8, 2025

MCP

Servers