Appearance
MCP 让 Kiro CLI 不只停留在本地代码上下文里，而是可以连接外部 server，调用文档检索、GitHub、AWS 或企业内部工具。本文用中文开发者熟悉的项目场景，说明 MCP 适合解决什么问题、如何配置 server，以及 agent 如何按权限使用这些 tools。
Kiro CLI MCP 入门：把外部工具接进 agent 工作流
Model Context Protocol（MCP）可以理解为 Kiro CLI 和外部能力之间的一层标准协议。Kiro 本身负责对话、推理和执行工作流，MCP server 则负责提供更专门的 tools 与上下文，比如搜索 AWS 文档、读取 GitHub issue、访问内部知识库，或者调用你自己封装的业务工具。
对中文开发者来说，MCP 最常见的价值不是“多装几个插件”，而是把原本需要切换网页、复制粘贴、手工查资料的步骤，变成 agent 可以按权限调用的工具链。
什么时候适合使用 MCP
可以优先考虑 MCP 的场景包括：
- 需要访问专门知识库，例如 AWS 文档、框架文档、团队内部文档。
- 需要接入外部服务或 API，例如 GitHub、数据库、工单系统。
- 需要让 agent 使用某个领域工具，例如云资源查询、日志搜索、代码仓库检索。
- 需要给团队定制 tools，把重复操作封装成稳定的 MCP server。
如果只是让 Kiro 阅读当前项目文件，通常不需要 MCP；如果 agent 必须“走出项目目录”访问外部系统，MCP 才是更合适的扩展方式。
配置 MCP server 的两种方式
使用 MCP 前，先确认目标 server 的运行前置条件已经安装好。例如某些 server 依赖 uv、Python、Docker，或者需要 API token。
方式一：通过命令行添加
适合临时验证或快速添加一个 server：
bash
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"这里的关键点是：
--name是 Kiro 识别这个 server 的名字。--scope决定配置作用范围，例如全局或当前 workspace。--command和--args负责启动本地 MCP server。--env用来传入运行时环境变量。
方式二：写入 mcp.json
更推荐把项目级配置放到 workspace 文件中：
- workspace 配置：
<project-root>/.kiro/settings/mcp.json - 用户级配置：
~/.kiro/settings/mcp.json
一个典型配置如下：
json
{
"mcpServers": {
"local-server-name": {
"command": "command-to-run-server",
"args": ["arg1", "arg2"],
"env": {
"ENV_VAR1": "value1",
"ENV_VAR2": "value2"
},
"disabled": false
},
"http-server-with-oauth": {
"type": "http",
"url": "https://api.example.com/mcp",
"oauth": {
"redirectUri": "127.0.0.1:8080",
"oauthScopes": ["read", "write"]
}
}
}
}本地 server 通常用 command 启动；远程 HTTP server 通常用 url 连接。需要 OAuth 的 HTTP MCP server 可以配置：
oauth.redirectUri：自定义 OAuth 回调地址，可选。oauth.oauthScopes：请求的 OAuth scopes，可选。
如果遇到 OAuth scope 报错，可以先把 scopes 设置为空数组：
json
"oauthScopes": []在 agent 配置中使用 MCP
如果你希望某个 agent 只拥有特定 server 的 tools，可以在 agent 配置里写 mcpServers：
json
{
"name": "myagent",
"description": "My special agent",
"mcpServers": {
"fetch": {
"command": "fetch3.1",
"args": []
}
},
"includeMcpJson": false
}includeMcpJson 决定这个 agent 是否同时继承用户级和 workspace 级的 MCP 配置：
false：只使用 agent 自己声明的 MCP server。true：除了 agent 自己的 server，还会加载用户级和 workspace 级配置。
团队里做权限隔离时，建议把高风险 tools 放进特定 agent，不要让所有 agent 默认继承。
常见问题排查
| 现象 | 处理方式 |
|---|---|
| 连接失败 | 检查 server 依赖是否安装，例如 Docker、Python、uv |
| 权限错误 | 检查 token、API key、OAuth 授权是否有效 |
| tool 没响应 | 查看 MCP server 日志，确认进程是否正常运行 |
| 配置未加载 | 检查 JSON 语法，并确认文件保存到了正确路径 |
tool 校验失败
如果看到类似 “The following tools have been excluded due to validation errors” 的提示，通常是 MCP server 暴露的 tool 定义不符合 Kiro 要求：
- tool name 加上 server 前缀后超过 64 个字符。
- tool name 包含非法字符，必须匹配
^[a-zA-Z][a-zA-Z0-9_]*$。 - tool description 为空。
这种问题一般要联系 MCP server 维护者修复 tool specification。
tool description 过大
如果看到 “The following tools have large descriptions which may impact agent performance”，说明某个 tool description 超过 10,000 字符。tool 仍然可以使用，但可能拖慢 agent 响应。更好的做法是让 server 维护者缩短描述，只保留 agent 决策需要的信息。
下一步
- 查看 MCP 配置详解，把 server 配置写得更稳。
- 参考 MCP 示例，从 AWS Documentation 或 GitHub server 开始试用。
- 阅读 MCP security 最佳实践，避免把敏感凭据和高风险 tools 暴露给 agent。
常见问题
MCP server 是不是必须运行在本机？
不一定。本地 server 常用 command 启动，远程 server 可以通过 HTTP URL 连接。但涉及凭据、代码和内部系统时，要优先确认 server 来源可信，并使用 HTTPS。
Kiro CLI 会自动信任 MCP tools 吗？
不应该把 MCP tools 当成天然可信。建议先阅读 tool description，确认权限范围，再决定是否让 agent 使用，必要时通过配置禁用高风险 tools。
一个项目可以配置多个 MCP server 吗？
可以。mcpServers 下可以声明多个 server。建议按用途命名，例如 aws-docs、github、internal-search，方便排查和权限管理。