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 --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 上可用的網頁設定不適用於 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 伺服器的憑證。保管庫是您註冊一次並透過 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 時重試。



後續步驟