English ← MyDocs

MCP 连接器

将 MCP 服务器连接到您的代理，以访问外部工具和数据源。

Claude 托管代理支持将模型上下文协议 (MCP) 服务器连接到您的代理。这使代理能够通过标准化协议访问外部工具、数据源和服务。

MCP 配置分为两个步骤：

  1. 代理创建声明代理连接的 MCP 服务器，包括名称和 URL。
  2. 会话创建通过引用预先注册的保险库为这些服务器提供认证。

这种分离使密钥不会出现在可重用的代理定义中，同时允许每个会话使用自己的凭据进行认证。

Note

所有托管代理 API 请求都需要 managed-agents-2026-04-01 beta 头。SDK 会自动设置该 beta 头。

在代理上声明 MCP 服务器

在创建代理时在 mcp_servers 数组中指定 MCP 服务器。每个服务器需要一个 type、一个唯一的 name 和一个 url。此阶段不提供认证令牌。

您在 MCP 服务器数组中分配的 name 用于引用工具数组中的 mcp_toolset 条目。

agent_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "name": "GitHub Assistant",
  "model": "claude-opus-4-7",
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ],
  "tools": [
    {"type": "agent_toolset_20260401"},
    {"type": "mcp_toolset", "mcp_server_name": "github"}
  ]
}
EOF
)
agent_id=$(jq -r '.id' <<<"$agent_response")

AGENT_ID=$(ant beta:agents create \
  --name "GitHub Assistant" \
  --model claude-opus-4-7 \
  --mcp-server '{type: url, name: github, url: "https://api.githubcopilot.com/mcp/"}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: mcp_toolset, mcp_server_name: github}' \
  --transform id --raw-output)

agent = client.beta.agents.create(
    name="GitHub Assistant",
    model="claude-opus-4-7",
    mcp_servers=[
        {
            "type": "url",
            "name": "github",
            "url": "https://api.githubcopilot.com/mcp/",
        },
    ],
    tools=[
        {"type": "agent_toolset_20260401"},
        {"type": "mcp_toolset", "mcp_server_name": "github"},
    ],
)

const agent = await client.beta.agents.create({
  name: "GitHub Assistant",
  model: "claude-opus-4-7",
  mcp_servers: [
    {
      type: "url",
      name: "github",
      url: "https://api.githubcopilot.com/mcp/",
    },
  ],
  tools: [
    { type: "agent_toolset_20260401" },
    { type: "mcp_toolset", mcp_server_name: "github" },
  ],
});

var agent = await client.Beta.Agents.Create(new()
{
    Name = "GitHub Assistant",
    Model = BetaManagedAgentsModel.ClaudeOpus4_7,
    McpServers =
    [
        new() { Type = "url", Name = "github", Url = "https://api.githubcopilot.com/mcp/" },
    ],
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = "agent_toolset_20260401",
        },
        new BetaManagedAgentsMcpToolsetParams { Type = "mcp_toolset", McpServerName = "github" },
    ],
});

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "GitHub Assistant",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: anthropic.BetaManagedAgentsModelClaudeOpus4_7,
	},
	MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{
		Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
		Name: "github",
		URL:  "https://api.githubcopilot.com/mcp/",
	}},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{
		{
			OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
				Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			},
		},
		{
			OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
				Type:          anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
				MCPServerName: "github",
			},
		},
	},
})
if err != nil {
	panic(err)
}

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("GitHub Assistant")
        .model(BetaManagedAgentsModel.CLAUDE_OPUS_4_7)
        .addMcpServer(
            BetaManagedAgentsUrlMcpServerParams.builder()
                .type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
                .name("github")
                .url("https://api.githubcopilot.com/mcp/")
                .build()
        )
        .addTool(
            BetaManagedAgentsAgentToolset20260401Params.builder()
                .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                .build()
        )
        .addTool(
            BetaManagedAgentsMcpToolsetParams.builder()
                .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
                .mcpServerName("github")
                .build()
        )
        .build()
);

$agent = $client->beta->agents->create(
    name: 'GitHub Assistant',
    model: 'claude-opus-4-7',
    mcpServers: [
        BetaManagedAgentsURLMCPServerParams::with(
            type: 'url',
            name: 'github',
            url: 'https://api.githubcopilot.com/mcp/',
        ),
    ],
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
        ),
        BetaManagedAgentsMCPToolsetParams::with(
            type: 'mcp_toolset',
            mcpServerName: 'github',
        ),
    ],
);

agent = client.beta.agents.create(
  name: "GitHub Assistant",
  model: "claude-opus-4-7",
  mcp_servers: [
    {
      type: "url",
      name: "github",
      url: "https://api.githubcopilot.com/mcp/"
    }
  ],
  tools: [
    {type: "agent_toolset_20260401"},
    {type: "mcp_toolset", mcp_server_name: "github"}
  ]
)
Tip

MCP 工具集默认使用 always_ask 权限策略，这需要在每次工具调用前获得用户批准。请参阅权限策略以配置此行为。

mcp_servers 字段参考

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

字段描述
type必需。必须为 "url"。
name必需。代理内此服务器的唯一名称（1-255 个字符）。用作 tools 数组中的 mcp_server_name，并在会话事件流中的 MCP 工具事件上显示。
url必需。远程 MCP 服务器的端点（最多 2048 个字符）。

约束：

  • 一个代理最多可以声明 20 个 MCP 服务器。服务器名称在数组中必须唯一。
  • 每个 mcp_servers 条目必须被 tools 数组中的 mcp_toolset 引用，每个 mcp_toolset 必须引用一个已声明的服务器。API 会拒绝具有未引用服务器或悬挂工具集的代理定义。

配置可用的 MCP 工具

mcp_toolset 条目支持与内置代理工具集相同的 default_config 和 configs 结构，应用于 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 工具集权限了解如何在 MCP 工具上设置 permission_policy 并处理确认请求。

MCP 工具输出处理

当 MCP 工具输出超过 100k token 时，它会自动写入沙箱中的文件。模型接收带有文件路径的截断预览，并可以从那里读取完整内容。

在会话创建时提供认证

启动会话时，传递 vault_ids 为您的 MCP 服务器提供凭据。保险库是凭据集合，您只需注册一次即可按 ID 引用。请参阅使用保险库认证了解如何创建保险库和管理凭据。

session_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id",
  "vault_ids": ["$vault_id"]
}
EOF
)
session_id=$(jq -r '.id' <<<"$session_response")

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --vault-id "$VAULT_ID" \
  --transform id --raw-output)

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

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  vault_ids: [vault.id],
});

var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    VaultIds = [vault.ID],
});

session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent:         anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
	EnvironmentID: environment.ID,
	VaultIDs:      []string{vault.ID},
})
if err != nil {
	panic(err)
}

var session = client.beta().sessions().create(
    SessionCreateParams.builder()
        .agent(agent.id())
        .environmentId(environment.id())
        .addVaultId(vault.id())
        .build()
);

$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    vaultIDs: [$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 完全匹配的凭据；如果没有匹配项，连接将以未认证方式尝试。请参阅添加凭据了解 static_bearer 和 mcp_oauth 凭据类型。

处理连接和认证失败

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

错误类型含义
mcp_connection_failed_error无法连接到 MCP 服务器（网络错误、超时或非认证 HTTP 失败）。
mcp_authentication_failed_errorMCP 服务器已连接但拒绝了附加保险库中的凭据。

您可以决定是否在此错误时阻止进一步交互、触发凭据轮换，或让会话在没有受影响服务器工具的情况下继续。连接会在下一次 session.status_idle 到 session.status_running 转换时重试。请参阅会话事件流了解如何消费 session.error 和其他事件。

支持的 MCP 服务器类型

Claude 托管代理连接到公开 HTTP 端点的远程 MCP 服务器，或通过 MCP 隧道连接到私有 MCP 服务器。服务器必须支持 MCP 协议的可流式 HTTP 传输。

有关 MCP 和构建 MCP 服务器的更多信息，请参阅 MCP 文档。