接入 MCP

MCP（Model Context Protocol）是连接第三方能力的标准协议。托管智能体原生支持接入远程 MCP 服务：你在智能体上声明服务地址，平台在会话运行时自动建立连接、拉取工具清单并暴露给模型——工具的发现、调用与结果回流全部由平台完成，你不需要编写任何 MCP 客户端代码。接入分为两步，职责清晰分离：

在智能体上声明连接：mcp_servers 只保存服务连接信息和非敏感请求头，不含任何凭据；
创建会话时注入凭据：访问凭据保存在凭据库（Vault）中，创建会话时按凭据库 ID 绑定，平台按服务地址自动匹配并注入。

这样的分离让同一份智能体配置可以服务多个最终用户：每个用户有自己的凭据库和凭据，智能体定义保持通用。

以下示例中的 API Key 从环境变量 KIMI_API_KEY 读取。

声明 MCP 服务

在创建或更新智能体时，通过 mcp_servers 字段声明 MCP 服务：

字段	类型	说明
`type`	string	服务类型，当前仅支持 `"url"`（远程服务，streamable HTTP 传输）
`name`	string	服务名称，在同一智能体内必须唯一；需要单独配置工具时，供 `mcp_toolset` 通过 `mcp_server_name` 引用
`url`	string	MCP 服务的端点地址，也是凭据库中凭据的匹配键
`headers`	object	可选的非敏感 HTTP 请求头，最多 16 条；请求中接受，响应中不回显

更新智能体时，mcp_servers 数组整体替换，请求中未出现的服务器不会保留。headers 的处理规则不同：缺省或为空时，若服务器的 name、type、url 均未变化，则继承原值；非空时整体替换该服务器的 headers，空字符串表示删除对应键。数量限制为每个智能体最多 20 个 MCP 服务。声明即暴露：连接成功后，该 MCP 服务提供的全部工具默认就会对模型可用，不需要额外声明 mcp_toolset。只有需要单独配置工具时，才在 tools 中使用 mcp_toolset，通过 mcp_server_name 引用同名的服务，并配置 default_config 或 configs。

curl -X POST https://api.moonshot.cn/v1/agents \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "项目助手",
    "model": {"id": "kimi-k3"},
    "system": "你是一个项目管理助手，帮用户跟踪任务进展。",
    "mcp_servers": [
      {
        "type": "url",
        "name": "todo",
        "url": "https://mcp.example.com/mcp"
      }
    ]
  }'

kha agents create --file - <<'JSON'
{
  "name": "项目助手",
  "model": {"id": "kimi-k3"},
  "system": "你是一个项目管理助手，帮用户跟踪任务进展。",
  "mcp_servers": [
    {
      "type": "url",
      "name": "todo",
      "url": "https://mcp.example.com/mcp"
    }
  ]
}
JSON

url 是凭据匹配的键，请以规范的服务端点形式填写，不要携带 query 参数、片段（fragment）或用户信息——这类地址无法与凭据库中的凭据匹配，平台会在创建时拒绝写入。

按工具配置开关与权限

需要精细控制时，可以在 tools 中用 mcp_toolset 引用某个已声明的服务，按工具覆盖配置；不需要覆盖时省略即可（默认全量暴露）：

{
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "todo",
      "default_config": {"enabled": true},
      "configs": [
        {"name": "delete_task", "enabled": false}
      ]
    }
  ]
}

配置项	说明
`mcp_server_name`	必填，引用同一智能体 `mcp_servers` 中声明的服务名称
`default_config.enabled`	该服务全部工具的默认开关，未设置时默认启用
`configs[].name`	MCP 服务提供的原始工具名
`configs[].enabled`	按工具覆盖开关；被禁用的工具不会进入模型上下文
`configs[].permission_policy`	按工具设置权限策略，详见权限策略

configs 引用了服务已不提供的工具名不会报错，该条配置被静默忽略——服务端的工具清单可能随版本变化，智能体配置不应因此失效。

权限策略支持 always_allow 和 always_ask。后者会在 agent.tool_use 事件后暂停执行，等待客户端回复 user.tool_confirmation；不希望智能体使用的工具请用 enabled: false 禁用，详见权限策略。

通过凭据库注入凭据

mcp_servers 中不放任何凭据。访问凭据保存在凭据库中，创建会话时在 resources 里绑定，不同凭据类型按各自的匹配条件处理：

environment_variable 凭据：用于允许的出站请求占位符替换，不作为 MCP 服务的连接凭据。真实凭据不会写入文件系统或环境变量；
MCP 凭据：mcp_oauth 和 static_bearer 按 MCP 服务地址（url）匹配。匹配成功后，连接携带相应的认证信息；没有匹配凭据时，平台会以匿名方式连接，不会自动补充认证信息；
多个凭据库命中同一服务地址：按 resources 中的绑定顺序，第一个匹配的凭据库生效。

带刷新配置的 mcp_oauth 凭据在 access token 过期时由平台自动刷新，无需你介入（OAuth Connect 落成的凭据在提供方发放刷新令牌时自带刷新配置）。

curl -X POST https://api.moonshot.cn/v1/sessions \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "kimi-api-version: 2026-09-01-beta" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_your_agent_id",
    "environment_id": "env_your_environment_id",
    "resources": [
      { "type": "vault", "vault_id": "vlt_your_vault_id" }
    ],
    "title": "整理本周任务"
  }'

kha sessions create --file - <<'JSON'
{
  "agent_id": "agent_your_agent_id",
  "environment_id": "env_your_environment_id",
  "resources": [
    { "type": "vault", "vault_id": "vlt_your_vault_id" }
  ],
  "title": "整理本周任务"
}
JSON

agent_id 用上一步创建智能体响应中的 id；environment_id、vault_id 分别来自执行环境和凭据库的创建响应。凭据库的绑定在创建会话时确定，创建后不能追加。凭据的轮换、归档对会话自动生效——平台在每次连接建立时重新解析凭据，最迟在下一次连接时拿到新值，无需重建会话。凭据的创建与管理详见凭据库；resources 绑定机制详见会话。

MCP OAuth Connect 授权

如果 MCP 服务使用 OAuth 2.0 授权，你不需要让最终用户手动复制 token。平台提供 MCP OAuth Connect 授权流：平台带着最终用户走完标准的 OAuth 授权码流程，授权完成后 token 自动落成凭据库凭据，你全程不经手任何凭据明文。授权入口有两处：

控制台 Connect

在凭据库页面或插件页面点击 Connect，按弹窗引导完成授权，token 自动入库。

授权会话 API

通过 POST /v1/vaults/{vault_id}/oauth-sessions 发起授权、引导用户打开授权页、轮询授权结果，适合嵌入你自己的产品界面。

授权完成后落成的凭据与手动创建的 mcp_oauth 凭据完全等价：同样的按地址匹配注入规则，同样由平台托管刷新。同一凭据库、同一服务地址已有活跃凭据时再次发起会返回 409，归档旧凭据后即可重新授权。完整的 API 流程与字段说明见凭据库的「MCP OAuth Connect 授权」一节。

运行时行为与注意事项

连接生命周期

MCP 连接跟随会话的执行节奏：会话每次被唤醒执行任务时，平台对每个声明的服务建立连接、拉取最新工具清单，执行结束后关闭。这意味着：

凭据轮换、工具清单变化最迟在下一次唤醒时生效；
每次唤醒建立连接会引入少量建连延迟，引用多个 MCP 服务时各服务的连接并行建立。

连接失败与降级

单个 MCP 服务不可用 不会导致会话失败，平台按服务粒度降级：

故障	行为
服务连不上、初始化超时、鉴权被拒绝	跳过该服务的全部工具，本轮模型看不到它们，会话与其他工具不受影响；下一次唤醒自动重连
工具调用过程中连接中断或超时	失败作为工具错误结果返回给模型，模型可以重试或调整策略；会话不中断
凭据库中无匹配凭据	匿名连接（合法配置，不报错误）

服务不可用时，模型在本轮执行中会认为智能体不具备对应能力。对关键业务依赖的 MCP 服务，建议在你的应用侧关注会话运行结果是否符合预期。

网络放行

会话所在执行环境若配置了 limited 网络策略，需要打开 allow_mcp_servers 开关（或将服务域名加入 allowed_hosts），MCP 连接才能到达对应的服务端点。

下一步

注入 MCP 访问凭据

创建凭据、走 OAuth Connect 授权流、轮换与归档。

配置工具与权限策略

了解内置工具集与 MCP 工具的组合方式。

设置工具权限

按工具配置权限策略，管控高风险 MCP 工具的执行方式。

放行 MCP 服务网络

配置网络策略，放行 MCP 服务端点。

启动带 MCP 工具的会话

创建会话并在 resources 中绑定凭据库。

开始使用

定义智能体

配置执行环境

运行会话

上下文与记忆

高级编排

最佳实践

常见问题

声明 MCP 服务

按工具配置开关与权限

通过凭据库注入凭据

MCP OAuth Connect 授权

控制台 Connect

授权会话 API

运行时行为与注意事项

连接生命周期

连接失败与降级

网络放行

下一步

注入 MCP 访问凭据

配置工具与权限策略

设置工具权限

放行 MCP 服务网络

启动带 MCP 工具的会话

​声明 MCP 服务

​按工具配置开关与权限

​通过凭据库注入凭据

​MCP OAuth Connect 授权

控制台 Connect

授权会话 API

​运行时行为与注意事项

​连接生命周期

​连接失败与降级

​网络放行

​下一步

注入 MCP 访问凭据

配置工具与权限策略

设置工具权限

放行 MCP 服务网络

启动带 MCP 工具的会话

声明 MCP 服务

按工具配置开关与权限

通过凭据库注入凭据

MCP OAuth Connect 授权

运行时行为与注意事项

连接生命周期

连接失败与降级

网络放行

下一步