MCP 连接器

Claude 托管智能体支持将 Model Context Protocol (MCP) 服务器连接到您的智能体。这使智能体能够通过标准化协议访问外部工具、数据源和服务。

MCP 配置分为两个步骤：

1. 创建智能体时，通过名称和 URL 声明智能体要连接的 MCP 服务器。
2. 创建会话时，通过引用预先注册的凭据库为这些服务器提供身份验证（请参阅使用凭据库进行身份验证）。

这种分离方式可将密钥排除在可复用的智能体定义之外，同时让每个会话使用自己的凭据进行身份验证。



在智能体上声明 MCP 服务器

创建智能体时，在 mcp_servers 数组中指定 MCP 服务器。每个服务器都需要 type、唯一的 name 和 url。此阶段不提供身份验证令牌。

每个声明的服务器还需要在 tools 数组中有一个匹配的 mcp_toolset 条目。工具集的 mcp_server_name 必须与服务器的 name 匹配。

AGENT_ID=$(ant beta:agents create --transform id --raw-output < github-assistant.agent.yaml)

name: GitHub Assistant
model:
  id: claude-opus-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: agent_toolset_20260401
  - type: mcp_toolset
    mcp_server_name: github



mcp_servers 字段参考

mcp_servers 数组中的每个条目定义一个连接。

约束条件：

• 一个智能体最多可声明 20 个 MCP 服务器。服务器名称在数组内必须唯一。
• 每个 mcp_servers 条目都必须被 tools 数组中的某个 mcp_toolset 引用，且每个 mcp_toolset 都必须引用一个已声明的服务器。API 会拒绝包含未被引用的服务器或悬空工具集的智能体定义。



配置可用的 MCP 工具

mcp_toolset 条目支持 default_config 对象和 configs 数组，应用于 MCP 服务器公开的工具。每个 configs 条目仅接受 name、enabled 和 permission_policy。与内置智能体工具集中的条目不同，MCP 工具条目不包含 type 字段，且 web_search 和 web_fetch 上可用的 Web 设置不适用于 MCP 工具。每个 configs 条目中的 name 是服务器报告的原始工具名称。

默认情况下，MCP 服务器公开的所有工具均已启用。如需仅启用特定工具，请将 default_config.enabled 设置为 false，并显式启用您需要的工具：

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "get_issue", "enabled": true },
    { "name": "list_issues", "enabled": true },
    { "name": "add_issue_comment", "enabled": true }
  ]
}

当服务器公开了许多工具但智能体只需要其中几个时，或者当您希望服务器运营方新增的工具在您审核之前保持禁用状态时，此模式非常有用。

如需禁用特定工具同时保持其余工具启用，请省略 default_config，并在各个条目上设置 enabled: false：

{
  "type": "mcp_toolset",
  "mcp_server_name": "github",
  "configs": [{ "name": "delete_repository", "enabled": false }]
}

有关通用的 default_config / configs 模式，请参阅配置工具集；有关在 MCP 工具上设置 permission_policy 以及处理确认请求的信息，请参阅 MCP 工具集权限。



MCP 工具输出处理

当 MCP 工具的输出超过 100,000 个字符（约 25,000 个令牌）时，会自动写入沙箱中的文件。模型会收到截断的预览以及文件路径，并可从该路径读取完整内容。



在创建会话时提供身份验证

启动会话时，传递 vault_ids 以为您的 MCP 服务器提供凭据。凭据库（vault）是您一次性注册并通过 ID 引用的凭据集合。有关如何创建凭据库和管理凭据，请参阅使用凭据库进行身份验证。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

凭据通过 URL 进行匹配，因此凭据库必须包含一个凭据，其 mcp_server_url 与 mcp_servers 中声明的 url 指向同一服务器。两个 URL 在匹配前都会进行规范化（协议和主机名转为小写，去除默认端口和末尾斜杠），因此主机名大小写、默认端口或末尾斜杠的差异不会影响匹配；但不同的路径、子域名或非默认端口则会导致不匹配。如果没有匹配项，则会尝试以未经身份验证的方式进行连接。有关 static_bearer 和 mcp_oauth 凭据类型，请参阅添加凭据。



处理连接和身份验证失败

会话创建不会验证 MCP 连接或凭据。如果 MCP 服务器无法访问或拒绝了提供的凭据，会话仍会启动且仍可进行交互。系统会发出一个 session.error 事件，其中包含受影响服务器的 mcp_server_name 和 retry_status：

您可以决定是否在出现此错误时阻止进一步交互、触发凭据轮换，或让会话在没有受影响服务器工具的情况下继续运行。连接会在下一次从 session.status_idle 转换到 session.status_running 时重试。



后续步骤