Kiro MCP 配置详解：JSON 结构、环境变量与多级作用域

Kiro 的 MCP 配置使用 JSON 格式，支持工作区级和用户级两套配置，可以分别管理项目专用和全局通用的 MCP servers。配置文件支持环境变量引用、工具禁用、自动批准等精细化控制选项。本文覆盖配置结构、字段含义、创建方式和故障排查，是接入 MCP server 的实操参考。

配置文件结构 #

MCP 配置文件使用 JSON 格式，基本结构如下：

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

远程 server 字段说明 #

本地 server 字段说明 #

配置文件位置 #

MCP server 可以在两个层级进行配置：

1. 工作区级：.kiro/settings/mcp.json

   • 仅对当前工作区生效
   • 适合项目专用的 MCP servers

2. 用户级：~/.kiro/settings/mcp.json

   • 对所有工作区全局生效
   • 适合频繁使用的通用 MCP servers

两个文件同时存在时，配置会合并，工作区设置优先级更高。

创建配置文件 #

通过命令面板 #

1. 打开命令面板：Mac 用 Cmd + Shift + P，Windows/Linux 用 Ctrl + Shift + P
2. 搜索 “MCP”，选择：
   • Kiro: Open workspace MCP config (JSON) — 工作区级配置
   • Kiro: Open user MCP config (JSON) — 用户级配置

通过 Kiro 面板 #

1. 打开 Kiro 面板
2. 点击 Open MCP Config 图标

配置示例（接入 Brave Search）：

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

环境变量 #

很多 MCP server 需要通过环境变量传递认证信息：

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

${VAR_NAME} 语法会自动展开为系统环境变量的值。出于安全考虑，只有在 Kiro 设置中明确批准的环境变量才会被展开，避免 MCP server 意外访问系统敏感变量。

临时禁用 server #

不想删除配置但需要暂停某个 server 时：

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

安全注意事项 #

• 使用 ${API_TOKEN} 引用方式，不要在配置文件中硬编码敏感值
• 不要将含有凭证的配置文件提交到版本控制
• 只连接来源可信的远程 server
• 在 autoApprove 中添加工具前，仔细审查工具权限

详细安全指南参见 MCP 安全最佳实践。

排查配置问题 #

配置不生效时，按以下顺序检查：

1. 验证 JSON 语法：缺少逗号、引号或括号是最常见错误，可以用在线 JSON 校验工具检查
2. 确认命令路径：在终端直接运行 command 字段的命令，确认它存在于 PATH 中
3. 检查环境变量：确认所需变量已在系统中设置，且变量名拼写正确
4. 保存配置文件：修改 MCP 配置后直接保存（Cmd+S），Kiro 会自动重连，无需重启

常见问题 #

Q：工作区配置和用户配置如果有同名 server，以哪个为准？

工作区配置优先级更高。如果两个文件中都定义了名为 github 的 server，Kiro 会使用工作区 .kiro/settings/mcp.json 中的配置。

Q：autoApprove: ["*"] 安全吗？

对于只读类工具（如文档搜索）使用 "*" 批量自动批准是可以接受的，但对于有写权限（删除、推送代码）的工具，强烈建议逐个手动审批，而不是使用通配符。

Q：配置文件保存后需要重启 Kiro 吗？

不需要。保存配置文件后 Kiro 自动检测变更并重连受影响的 server，修改立即生效。