Model Context Protocol (MCP)

Model Context Protocol (MCP) extends Kiro's capabilities by connecting to specialized servers that provide additional tools and context. This guide helps you set up, configure, and use MCP servers with Kiro CLI.

What is MCP?

MCP is a protocol that allows Kiro to communicate with external servers to access specialized tools and information. For example, the AWS Documentation MCP server provides tools to search, read, and get recommendations from AWS documentation directly within Kiro.

With MCP, you can:

• Access specialized knowledge bases and documentation
• Integrate with external services and APIs
• Extend Kiro's capabilities with domain-specific tools
• Create custom tools for your specific workflows

Setting up MCP

Before using MCP, make sure you have any specific prerequisites for the MCP servers you want to use (listed in each server's documentation)

There are two ways of configuring MCP servers in Kiro CLI:

Command line

# Add new MCP server
kiro-cli mcp add \
  --name "awslabs.aws-documentation-mcp-server" \
  --scope global \
  --command "uvx" \
  --args "awslabs.aws-documentation-mcp-server@latest" \
  --env "FASTMCP_LOG_LEVEL=ERROR" \
  --env "AWS_DOCUMENTATION_PARTITION=aws"

mcp.json file

MCP servers can be loaded from the MCP configuration file in your workspace (<project-root>/.kiro/settings/mcp.json) or from user level settings (~/.kiro/settings/mcp.json)

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

Agent configuration

The mcpServers field specifies which MCP servers the agent has access to. Each server is defined with a command and optional arguments.

{
  "name": "myagent",
  "description": "My special agent",
  "mcpServers": {
    "fetch": {
      "command": "fetch3.1",
      "args": []
    }
  },
  "includeMcpJson": false
}

The includeMcpJson field determines whether to include MCP servers defined in the workspace and user level MCP configuration files. When set to true, the agent will have access to all MCP servers defined in the user and workspace level configurations in addition to those defined in the agent's mcpServers field.

Troubleshooting

Common issues and solutions

Tool validation errors

If you see "The following tools have been excluded due to validation errors", the tool fails one of these requirements:

• Tool name exceeds 64 characters (including server prefix)
• Tool name contains invalid characters (must match ^[a-zA-Z][a-zA-Z0-9_]*$)
• Tool description is empty

Contact the MCP server maintainer to fix the tool specification.

Large description warnings

If you see "The following tools have large descriptions which may impact agent performance", a tool description exceeds 10,000 characters. The tool still works but may slow down responses. Consider asking the server maintainer to shorten the description.

Additional resources

• Official MCP Documentation

Next steps

Now that you understand MCP basics, explore these resources:

• Examples - Practical examples of using MCP servers with Kiro CLI
• Security Best Practices - Best practices for secure MCP usage