MCP Registry

Enterprise MCP server governance allowing administrators to control which servers users can access.

Pro-tier customers using IAM Identity Center can have MCP server access controlled through an MCP registry. When configured by administrators, users can only use MCP servers explicitly allowed in the registry. Provides centralized governance for enterprise deployments.

Without Registry (default):

• Users can add any MCP server
• Servers configured in agent files or via CLI
• No central control

With Registry (enterprise):

• Administrator configures allowed servers
• Users select from registry list
• Cannot add custom servers through the /mcp add picker (personal servers in mcp.json still load)
• Centralized governance and security

/mcp add

Shows interactive list of servers from organization's registry.

# Add specific server
kiro-cli mcp add --name myserver

# Add to workspace
kiro-cli mcp add --scope workspace

# Add to specific agent
kiro-cli mcp add --agent myagent

# Interactive selection
kiro-cli mcp add

/mcp remove

Interactive menu to select server to remove.

kiro-cli mcp remove --name <server-name>

/mcp list

Shows:

• All locally configured MCP servers
• Server status and configuration
• Available tools from each server

Even with registry mode enabled, you can customize servers using registry overrides in your agent configuration or in an mcp.json file (global ~/.kiro/mcp.json or workspace .kiro/mcp.json). Your values are merged on top of registry defaults — for example, if the registry sets NODE_ENV=development and your override sets NODE_ENV=production, the server runs with NODE_ENV=production. The env and headers objects merge per-key, so registry defaults you don't override are preserved.

The env, headers, and timeout overrides you define for a registry-type entry flow through to the launched server, so the running process uses your customized values.

Use "type": "registry" with optional env, headers, or timeout overrides:

{
  "mcpServers": {
    "github": {
      "type": "registry",
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN",
        "GITHUB_ORG": "my-org"
      },
      "timeout": 60000
    }
  }
}

Override fields:

• Local (stdio) servers — env (environment variables), timeout (request timeout in ms)
• Remote (HTTP) servers — headers (HTTP headers), timeout (request timeout in ms)

Changes made via /mcp add and /mcp remove are automatically written back to your agent's configuration file. Added servers remain available after restarting the CLI, and removed servers stay removed across sessions — no manual editing required.

When a registry is active, personal MCP servers you define in mcp.json (global ~/.kiro/mcp.json or workspace .kiro/mcp.json) load alongside the registry-managed servers. You get both your own servers and the servers your organization provides through the registry in the same session — define them directly in mcp.json, since the /mcp add picker only lists registry servers.

/mcp add

Output:

Select MCP server from registry:
  git-server (Git operations)
  github-server (GitHub integration)
  aws-tools (AWS operations)

kiro-cli mcp add --name git-server --agent rust-dev

Adds git-server to rust-dev agent configuration.

For remote (HTTP) registry servers, override headers and timeout the same way:

{
  "mcpServers": {
    "github": {
      "type": "registry",
      "headers": {
        "X-Team-Id": "platform"
      },
      "timeout": 30000
    }
  }
}

The server uses the registry's URL and OAuth configuration, plus your custom headers and timeout.

Symptom: Cannot use MCP at all
Cause: Organization disabled MCP entirely
Solution: Contact administrator for MCP access

Symptom: Error fetching MCP configuration
Cause: Network issue or server error
Solution: Temporary issue - retry later or contact administrator

Symptom: Server not in the /mcp add list
Cause: The picker only lists servers from your organization's registry
Solution: Define the server directly in mcp.json (it loads alongside registry servers), or request that an administrator add it to the registry

Symptom: Needed server not available
Cause: Not added to organization's registry
Solution: Contact administrator to request server addition

• Registry mode only for Pro-tier with IAM Identity Center
• Cannot add servers not in the registry through the /mcp add picker
• Administrator controls available servers
• Personal servers defined in mcp.json load alongside registry servers when the registry is active

Registry source: Configured by administrator at organization level

Scope options:

• Global: ~/.kiro/mcp.json
• Workspace: .kiro/mcp.json
• Agent-specific: In agent configuration

Customization: env, headers, and timeout overrides for registry-type entries flow through to the launched server, even in registry mode

Fallback: If registry unavailable, MCP functionality disabled

• Learn about MCP Configuration
• Review MCP Governance for administrators
• See MCP Examples
• Understand MCP Security