MCP 連接器

Claude Managed Agents 支援將 Model Context Protocol (MCP) 伺服器連接到您的代理。這讓代理能夠透過標準化協定存取外部工具、資料來源和服務。

MCP 設定分為兩個步驟：

1. 代理建立時，透過名稱和 URL 宣告代理要連接的 MCP 伺服器。
2. 工作階段建立時，透過參照預先註冊的 vault（保管庫）為這些伺服器提供驗證。

這種分離方式可將機密資訊排除在可重複使用的代理定義之外，同時讓每個工作階段使用自己的憑證進行驗證。



在代理上宣告 MCP 伺服器

建立代理時，在 mcp_servers 陣列中指定 MCP 伺服器。每個伺服器都需要 type、唯一的 name 和 url。此階段不提供驗證權杖。

每個宣告的伺服器也需要在 tools 陣列中有對應的 mcp_toolset 項目。工具集的 mcp_server_name 必須與伺服器的 name 相符。

AGENT_ID=$(ant beta:agents create \
  --name "GitHub Assistant" \
  --model claude-opus-4-8 \
  --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)



mcp_servers 欄位參考

mcp_servers 陣列中的每個項目定義一個連線。

限制：

• 一個代理最多可宣告 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 工具上設定 permission_policy 及處理確認請求，請參閱 MCP 工具集權限。



MCP 工具輸出處理

當 MCP 工具輸出超過 100,000 個 token 時，會自動寫入沙箱中的檔案。模型會收到截斷的預覽以及檔案路徑，並可從該處讀取完整內容。



在工作階段建立時提供驗證

啟動工作階段時，傳遞 vault_ids 以為您的 MCP 伺服器提供憑證。Vault（保管庫）是您註冊一次後即可透過 ID 參照的憑證集合。有關如何建立 vault 和管理憑證，請參閱使用 vault 進行驗證。

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

憑證是透過 URL 進行比對，因此 vault 必須包含一個 mcp_server_url 與 mcp_servers 中宣告的 url 完全相符的憑證。如果沒有相符的憑證，則會嘗試以未驗證的方式連線。有關 static_bearer 和 mcp_oauth 憑證類型，請參閱新增憑證。



處理連線和驗證失敗

工作階段建立時不會驗證 MCP 連線或憑證。如果 MCP 伺服器無法連線或拒絕提供的憑證，工作階段仍會啟動且仍可進行互動。系統會發出 session.error 事件，其中包含受影響伺服器的 mcp_server_name 和 retry_status：

您可以決定是否要因此錯誤而阻止進一步的互動、觸發憑證輪替，或讓工作階段在沒有受影響伺服器工具的情況下繼續進行。連線會在下一次從 session.status_idle 轉換到 session.status_running 時重試。



後續步驟