古法编程

Appearance

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：

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,
      "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 字段 ​

字段类型必填说明
commandString是启动 MCP server 的命令
argsArray否传给命令的参数
envObject否server 进程使用的环境变量
disabledBoolean否是否禁用该 server，默认 false
autoApproveArray否不再提示、自动批准的 tool 名称
disabledToolsArray否不提供给 Agent 调用的 tool 名称

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

远程 server 字段 ​

字段类型必填说明
urlString是远程 MCP server 的 HTTPS endpoint；localhost 可使用 HTTP
headersObject否连接 server 时附带的 HTTP headers
envObject否server 进程使用的环境变量
disabledBoolean否是否禁用该 server，默认 false
autoApproveArray否不再提示、自动批准的 tool 名称
disabledToolsArray否不提供给 Agent 调用的 tool 名称

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

常用配置示例 ​

使用环境变量的本地 server ​

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

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

使用 headers 的远程 server ​

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

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

同时配置多个 server ​

json
{
  "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 会完整覆盖 ​

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

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

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

不同名字会叠加加载 ​

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

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

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

用覆盖禁用 server ​

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

Result: fetch server 不会启动

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

环境变量写法 ​

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

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

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

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

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

临时禁用 server ​

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

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

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

禁用特定 tools ​

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

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

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

查看当前加载的 server ​

在交互式 chat session 中输入：

text
/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 或密钥管理服务保存真实凭据。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策