Configuration

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

Configuration File Structure

MCP configuration files use JSON format with the following structure:

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

Configuration Properties

Configuration Locations

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.

Creating Configuration Files

Using the Command Palette

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

Using the Kiro Panel

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": "your-api-key"
      }
    }
  }
}

Environment Variables

Many MCP servers require environment variables for authentication or configuration:

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

Disabling Servers Temporarily

To temporarily disable an MCP server without removing its configuration:

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

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

Troubleshooting Configuration Issues

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. Restart Kiro:

   • Changes to MCP configuration require a restart
   • Close and reopen Kiro to apply changes