Claude Platform Docs
Managed Agents定義您的代理

MCP 連接器

將 MCP 伺服器連接到您的代理，以存取外部工具和資料來源。

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

MCP 設定分為兩個步驟：

  1. 建立代理時，以名稱和 URL 宣告代理要連接哪些 MCP 伺服器。
  2. 建立工作階段時，透過參照預先註冊的 vault（保管庫）為這些伺服器提供驗證（請參閱使用 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)
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 陣列中的每個項目定義一個連線。

欄位說明
type必填。必須為 "url"。
name必填。此伺服器在代理內的唯一名稱（1–255 個字元）。用作 tools 陣列中的 mcp_server_name，並會顯示在工作階段事件串流中的 MCP 工具事件上。
url必填。遠端 MCP 伺服器的端點（最多 2,048 個字元）。傳輸需求請參閱支援的 MCP 伺服器類型。

限制條件：

  • 一個代理最多可宣告 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 個 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 相同的伺服器。兩個 URL 在比對前都會先正規化（scheme 和主機名稱轉為小寫，移除預設連接埠和結尾斜線），因此主機名稱大小寫、預設連接埠或結尾斜線的差異不會妨礙比對；但不同的路徑、子網域或非預設連接埠則會。若沒有任何相符的憑證，則會嘗試以未驗證的方式連線。關於 static_bearer 和 mcp_oauth 憑證類型，請參閱新增憑證。

處理連線與驗證失敗

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

錯誤類型意義
mcp_connection_failed_error無法連線至 MCP 伺服器（網路錯誤、逾時，或非驗證相關的 HTTP 失敗）。
mcp_authentication_failed_error與 MCP 伺服器的驗證失敗：伺服器拒絕了所附加 vault 中的憑證、在未設定相符憑證時要求驗證，或 OAuth 權杖重新整理失敗。

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

後續步驟

權限政策

控制代理與 MCP 工具何時執行。

工作階段事件串流

傳送事件、串流回應，並在執行過程中中斷或重新導向您的工作階段。

支援的 MCP 伺服器類型

遠端 MCP 伺服器的傳輸需求。

Was this page helpful?