--- title: MCP 連接器 url: https://platform.claude.com/docs/zh-TW/managed-agents/mcp-connector description: 將 MCP 伺服器連接到您的代理，以存取外部工具和資料來源。 featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Claude Managed Agents 支援將 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 伺服器連接到您的代理。這讓代理能夠透過標準化協定存取外部工具、資料來源和服務。 MCP 設定分為兩個步驟： 1. **建立代理**時，以名稱和 URL 宣告代理要連接哪些 MCP 伺服器。 2. **建立工作階段**時，透過參照預先註冊的 vault（保管庫）為這些伺服器提供驗證（請參閱[使用 vault 進行驗證](https://platform.claude.com/docs/zh-TW/managed-agents/vaults)）。 這種分離方式讓機密資訊不會出現在可重複使用的代理定義中，同時讓每個工作階段都能使用自己的憑證進行驗證。 ## 在代理上宣告 MCP 伺服器 建立代理時，在 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 陣列中指定 MCP 伺服器。每個伺服器都需要一個 `type` (csharp, go: `Type`)、一個唯一的 `name` (csharp, go: `Name`)，以及一個 `url` (csharp: `Url`; go: `URL`)。此階段不提供任何驗證權杖。 每個宣告的伺服器也需要在 `tools` (csharp, go: `Tools`) 陣列中有一個對應的 `mcp_toolset` 項目。工具集的 `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) 必須與伺服器的 `name` (csharp, go: `Name`) 相符。 ```bash cURL 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 '{ "name": "GitHub Assistant", "model": "claude-opus-5-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"} ] }' ``` ```bash CLI ant apply github-assistant.md ``` ```markdown --- name: GitHub Assistant model: claude-opus-5-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 --- ``` ```python Python agent = client.beta.agents.create( name="GitHub Assistant", model="claude-opus-5-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"}, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "GitHub Assistant", model: "claude-opus-5-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" } ] }); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "GitHub Assistant", Model = BetaManagedAgentsModel.ClaudeOpus5_5, 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" }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "GitHub Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, 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) } ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("GitHub Assistant") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .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() ); ``` ```php PHP $agent = $client->beta->agents->create( name: 'GitHub Assistant', model: 'claude-opus-5-5', 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', ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "GitHub Assistant", model: "claude-opus-5-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 工具集的權限政策預設為 `always_ask`，每次工具呼叫前都需要使用者核准。請參閱[權限政策](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies)以設定此行為。 ### `mcp_servers` 欄位參考 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 陣列中的每個項目定義一個連線。 | 欄位 | 說明 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` (csharp, go: `Type`) | 必填。必須為 `"url"`。 | | `name` (csharp, go: `Name`) | 必填。此伺服器在代理內的唯一名稱（1–255 個字元）。用作 `tools` (csharp, go: `Tools`) 陣列中的 `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`)，並會顯示在[工作階段事件串流](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming)中的 MCP 工具事件上。 | | `url` (csharp: `Url`; go: `URL`) | 必填。遠端 MCP 伺服器的端點（最多 2,048 個字元）。傳輸需求請參閱[支援的 MCP 伺服器類型](https://platform.claude.com/docs/zh-TW/managed-agents/reference#supported-mcp-server-types)。 | 限制條件： * 一個代理最多可宣告 20 個 MCP 伺服器。伺服器名稱在陣列中必須唯一。 * 每個 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 項目都必須被 `tools` (csharp, go: `Tools`) 陣列中的某個 `mcp_toolset` 參照，且每個 `mcp_toolset` 都必須參照一個已宣告的伺服器。API 會拒絕含有未被參照的伺服器或懸空工具集的代理定義。 ## 設定可用的 MCP 工具 `mcp_toolset` 項目支援一個 `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) 物件和一個 `configs` (csharp, go: `Configs`) 陣列，套用於 MCP 伺服器所公開的工具。每個 `configs` (csharp, go: `Configs`) 項目僅接受 `name` (csharp, go: `Name`)、`enabled` (csharp, go: `Enabled`) 和 `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)。與內建代理工具集中的項目不同，MCP 工具項目不接受 `type` (csharp, go: `Type`) 欄位，且 `web_search` 和 `web_fetch` 上可用的[網頁設定](https://platform.claude.com/docs/zh-TW/managed-agents/tools-web-restrictions#settings)不適用於 MCP 工具。每個 `configs` (csharp, go: `Configs`) 項目中的 `name` (csharp, go: `Name`) 是伺服器所回報的純工具名稱。 預設情況下，MCP 伺服器公開的所有工具都會啟用。若只想啟用特定工具，請將 `default_config.enabled` 設為 `false`，並明確啟用您想要的工具： ```json { "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`： ```json { "type": "mcp_toolset", "mcp_server_name": "github", "configs": [{ "name": "delete_repository", "enabled": false }] } ``` 關於一般的 `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`) 模式，請參閱[設定工具集](https://platform.claude.com/docs/zh-TW/managed-agents/tools#configuring-the-toolset)；關於在 MCP 工具上設定 `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) 以及處理確認請求，請參閱 [MCP 工具集權限](https://platform.claude.com/docs/zh-TW/managed-agents/permission-policies#mcp-toolset-permissions)。 ### MCP 工具輸出處理 當 MCP 工具輸出超過 100,000 個字元（約 25,000 個 token）時，會自動寫入沙箱中的檔案。模型會收到包含檔案路徑的截斷預覽，並可從該處讀取完整內容。 ## 在建立工作階段時提供驗證 啟動工作階段時，傳入 `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) 以為您的 MCP 伺服器提供憑證。Vault 是您註冊一次並透過 ID 參照的憑證集合。關於如何建立 vault 和管理憑證，請參閱[使用 vault 進行驗證](https://platform.claude.com/docs/zh-TW/managed-agents/vaults)。 使用 `limited` [環境](https://platform.claude.com/docs/zh-TW/managed-agents/environments#networking)時，若代理宣告的 MCP 伺服器主機不在 `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) 中，建立工作階段會失敗並回傳 400 錯誤。在環境的網路設定中將 `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) 設為 `true` 即可關閉此檢查。 ```bash cURL 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 '{ "agent": "'"$agent_id"'", "environment_id": "'"$environment_id"'", "vault_ids": ["'"$vault_id"'"] }' ``` ```bash CLI ant beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ENVIRONMENT_ID" \ --vault-id "$VAULT_ID" ``` ```python Python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, vault_ids=[vault.id], ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = agent.ID, EnvironmentID = environment.ID, VaultIds = [vault.ID], }); ``` ```go Go 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) } ``` ```java Java var session = client.beta().sessions().create( SessionCreateParams.builder() .agent(agent.id()) .environmentId(environment.id()) .addVaultId(vault.id()) .build() ); ``` ```php PHP $session = $client->beta->sessions->create( agent: $agent->id, environmentID: $environment->id, vaultIDs: [$vault->id], ); ``` ```ruby Ruby session = client.beta.sessions.create( agent: agent.id, environment_id: environment.id, vault_ids: [vault.id] ) ``` 憑證是依 URL 進行比對的，因此 vault 中必須包含一個憑證，其 `mcp_server_url` (java: `mcpServerUrl`; php: `mcpServerURL`; csharp: `McpServerUrl`; go: `MCPServerURL`) 指向與 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 中宣告的 `url` (csharp: `Url`; go: `URL`) 相同的伺服器。兩個 URL 在比對前都會經過正規化（scheme 和主機轉為小寫，並移除預設連接埠和結尾斜線），因此主機大小寫、預設連接埠或結尾斜線的差異不會妨礙比對；但不同的路徑、子網域或非預設連接埠則會。若沒有相符的憑證，則會嘗試以未驗證的方式連線。關於 `static_bearer` 和 `mcp_oauth` 憑證類型，請參閱[新增憑證](https://platform.claude.com/docs/zh-TW/managed-agents/vaults#add-a-credential)。 ### 處理連線與驗證失敗 建立工作階段時不會驗證 MCP 連線能力或憑證。但它會根據環境的網路設定檢查每個已宣告伺服器的主機：使用 `limited` 環境時，若主機不被允許，建立工作階段會失敗並回傳 400 錯誤，如[在建立工作階段時提供驗證](https://platform.claude.com/docs/zh-TW/managed-agents/mcp-connector#provide-authentication-at-session-creation)中所述。若 MCP 伺服器無法連線或拒絕所提供的憑證，工作階段仍會啟動，且仍可進行互動。系統會發出一個 [`session.error`](https://platform.claude.com/docs/zh-TW/managed-agents/reference#event-types) 事件，其中包含受影響伺服器的 `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) 以及一個 `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`)： | 錯誤類型 | 意義 | | --------------------------------- | ------------------------------------------------------------------- | | `mcp_connection_failed_error` | 無法連線至 MCP 伺服器（網路錯誤、逾時，或非驗證相關的 HTTP 失敗）。 | | `mcp_authentication_failed_error` | 與 MCP 伺服器的驗證失敗：伺服器拒絕了所附加 vault 中的憑證、在未設定相符憑證時要求驗證，或 OAuth 權杖重新整理失敗。 | 您可以決定是否因此錯誤而阻止進一步互動、觸發憑證輪替，或讓工作階段在沒有受影響伺服器工具的情況下繼續執行。連線會在下一次從 `session.status_idle` 轉換為 `session.status_running` 時重試。 ## 後續步驟 控制代理與 MCP 工具何時執行。 傳送事件、串流回應，並在執行過程中中斷或重新導向您的工作階段。 遠端 MCP 伺服器的傳輸需求。