Kiro CLI 的 MCP 配置核心是 mcpServers：本地 server 用 command 启动，远程 server 用 URL 连接，再通过 env、headers、disabledTools 等字段控制权限和行为。本文整理配置结构、加载优先级、OAuth 刷新与排查方法，帮助你把 MCP 接入做得可维护。

Kiro CLI MCP 配置：稳定管理 server、tools 与权限边界 #

MCP 配置文件是 Kiro CLI 加载外部 server 的入口。写得随意时，agent 可能找不到 tools、拿不到环境变量，甚至误用危险能力；写得清晰时，团队可以把不同 server 分层放到全局、workspace 或 agent 配置里，让权限边界更稳定。

配置文件基本结构 #

MCP 配置使用 JSON，核心字段是 mcpServers：

{
  "mcpServers": {
    "local-server-name": {
      "command": "command-to-run-server",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "hard-coded-variable",
        "ENV_VAR2": "${EXPANDED_VARIABLE}"
      },
      "disabled": false,
      "disabledTools": ["tool_name3"]
    },
    "remote-server-name": {
      "url": "https://endpoint.to.connect.to",
      "headers": {
        "HEADER1": "value1",
        "HEADER2": "value2"
      },
      "disabled": false,
      "disabledTools": ["tool_name3"]
    }
  }
}

可以把它理解成一张 server 清单：每个 key 是 server 名称，value 是连接方式、环境变量、禁用状态和 tool 控制策略。

本地 server 字段 #

本地 server 适合需要在开发机启动进程的场景，例如 uvx、npx、docker run。

远程 server 字段 #

远程 server 更像 API 接入，重点是 HTTPS、headers 和鉴权方式。不要把 token 直接写死在配置里。

常用配置示例 #

使用环境变量的本地 server #

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

这里 ${BRAVE_API_KEY} 会从当前 shell 环境变量展开。这样配置文件可以提交模板，但真实密钥不进入版本库。

使用 headers 的远程 server #

{
  "mcpServers": {
    "api-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-Custom-Header": "value"
      }
    }
  }
}

如果远程 server 使用 Bearer Token，建议只在环境变量或系统凭据管理器里保存真实 token。

同时配置多个 server #

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

命名时尽量使用稳定、可读的名字。后续排查日志、禁用 tools、配置 agent 时都会依赖这些名称。

加载优先级 #

当多个配置同时定义了同名 MCP server，Kiro CLI 按以下顺序加载，优先级从高到低：

1. Agent 配置中的 mcpServers 字段。
2. Workspace MCP JSON：.kiro/settings/mcp.json。
3. Global MCP JSON：~/.kiro/settings/mcp.json。

同名 server 会完整覆盖 #

Agent config:     { "fetch": { command: "fetch-v2" } }
Workspace config: { "fetch": { command: "fetch-v1" } }
Global config:    { "fetch": { command: "fetch-old" } }

Result: 只使用 agent config 中的 fetch-v2

这不是字段级合并，而是同名 server 的高优先级配置覆盖低优先级配置。

不同名字会叠加加载 #

Agent config:     { "fetch": {...} }
Workspace config: { "git": {...} }
Global config:    { "aws": {...} }

Result: fetch、git、aws 三个 server 都会被加载

因此团队配置里要避免随意重名。需要覆盖时就明确重名；需要共存时就使用不同名称。

用覆盖禁用 server #

Agent config:     { "fetch": { command: "...", disabled: true } }
Workspace config: { "fetch": { command: "..." } }

Result: fetch server 不会启动

这适合给特定 agent 收窄能力范围。

环境变量写法 #

很多 MCP server 需要 API key、token 或连接字符串。推荐使用 ${VARIABLE_NAME} 引用环境变量：

{
  "mcpServers": {
    "server-name": {
      "env": {
        "API_KEY": "${YOUR_API_KEY}",
        "DEBUG": "true",
        "TIMEOUT": "30000"
      }
    }
  }
}

运行 Kiro CLI 前，先在 shell 中设置变量：

export YOUR_API_KEY="your-actual-key"
export DEBUG="true"

Windows 用户如果使用 PowerShell 或 Git Bash，要确认变量设置在 Kiro CLI 实际启动的 shell 环境里。

临时禁用 server #

不想删除配置，只想暂时停用：

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

这种做法适合排查问题：先禁用可疑 server，再观察 agent 行为是否恢复正常。

禁用特定 tools #

如果某个 server 大部分能力有用，但少数 tools 风险较高，可以使用 disabledTools：

{
  "mcpServers": {
    "server-name": {
      "disabledTools": ["delete_file", "execute_command"]
    }
  }
}

建议对删除文件、执行命令、写数据库、发起生产环境变更等 tools 默认保持谨慎。

查看当前加载的 server #

在交互式 chat session 中输入：

/mcp

Kiro 会显示当前活跃的 MCP servers、可用 tools，以及 registry 管理状态。排查“为什么 agent 看不到某个 tool”时，先看这里。

OAuth 认证与会话中刷新 #

远程 MCP server 如果需要 OAuth，Kiro CLI 会在连接时自动处理基于浏览器的 OAuth flow。

如果 token 在 session 中过期，而且没有 refresh token，Kiro CLI 会自动触发新的浏览器认证流程。你不需要重启 session，重新认证完成后 MCP server 会用新 token 重连。

这对短生命周期 token 的身份提供商尤其有用。

配置排查清单 #

1. 检查 JSON 语法：有没有漏逗号、引号、括号。
2. 检查命令路径：command 是否在 PATH 中，能否在终端直接运行。
3. 检查环境变量：变量是否真的设置，名称是否拼错。
4. 检查加载位置：确认 workspace 配置和用户级配置是否写在正确路径。
5. 检查优先级：同名 server 是否被 agent 配置覆盖。

安全提醒 #

• 敏感值使用 ${API_TOKEN} 这类环境变量引用，不要硬编码。
• 不要把含凭据的配置文件提交到版本库。
• 只连接可信的远程 MCP server。
• 用 disabledTools 限制危险操作。
• 谨慎使用 autoApprove，尤其是会写文件、执行命令或修改远程系统的 tools。

更多安全建议见 MCP security 最佳实践。

常见问题 #

workspace 配置和 global 配置应该怎么选？ #

团队项目共享的 server 放 workspace；你个人常用、跨项目复用的 server 放 global。涉及团队安全策略时，优先以 workspace 或企业 registry 为准。

同名 server 会不会把字段合并？ #

不会。高优先级配置会覆盖低优先级的同名 server。需要保留两个版本时，请使用不同 server 名称。

可以把 API token 写进 mcp.json 吗？ #

技术上可以，但不建议。更安全的做法是用环境变量、系统 keychain 或密钥管理服务保存真实凭据。