Claude API 接入遠程 MCP(MCP Connector)怎麼寫:Messages 請求直連、認證與限制

不用自己在後端寫 MCP 客戶端循環,Claude API 的 MCP Connector 支持在 Messages 請求裏通過 mcp_servers 和 mcp_toolset 直連遠程伺服器。本文講清 beta 請求頭、Bearer 認證、工具白名單與當前限制。

NNathaniel bigo··原創首發·AI 輔助撰寫
12 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 其他 帳號

結論先說

  1. 服務端直連,免去自建 MCP 客戶端循環:在 Messages API 請求裏聲明 mcp_servers 和 mcp_toolset,Anthropic 服務端會自動連接你的遠程 MCP 地址、拉取工具列表並在同一次請求內完成調用與結果回傳。
  2. 必須攜帶專用 Beta 標識:當前調用需在 HTTP 頭傳入 "anthropic-beta": "mcp-client-2025-11-20"(使用官方 SDK 時走 client.beta.messages.create 並傳 betas=["mcp-client-2025-11-20"])。
  3. 只支持遠程 HTTP 傳輸,不支持本地 stdio:目標 MCP 伺服器必須提供公網可達的 HTTPS 地址(支持 Streamable HTTP 或 SSE 傳輸),且目前只支持 MCP 的 Tools(工具) 能力,不支持 Resources 和 Prompts。
  4. 生產環境務必用 mcp_toolset 做工具收斂:通過 default_config 和 configs 可以只放行必要的幾個工具,或開啟 defer_loading 避免一次性把幾十個工具描述全塞進上下文。
  5. 國內免卡開通與帳號服務入口:自有帳號免上號自助開通可見本站 Claude Pro 充值頁 與 Claude Max 充值頁;缺可用帳號或遇身份核驗可查看 Claude 註冊說明 與 Claude KYC 認證協助。

MCP Connector 直連遠程工具四步

圖:本站根據 Claude 官方文檔:MCP connector 整理的示意圖

本文根據 Claude 開發者平台官方文檔《MCP connector》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 官方網站。

適用於誰

  • 搜「claude api mcp connector」「claude messages api 調用遠程 mcp」的後端與全棧開發者;
  • 想讓線上業務接口直接調用 Notion、Linear 或公司自建遠程 MCP 工具,不想自己在業務服務裏維護一套 MCP 客戶端狀態機的人;
  • 連上遠程 MCP 後發現工具太多導致輸入 token 激增,想按白名單篩選工具的人。

如果你不是自己寫 API 代碼,而是想在網頁版或本地命令行裏直接掛載現成連接器,可以看 /guides/claude-connectors 或 /guides/claude-code-mcp-setup。

一、最小可用請求怎麼寫(Python 與 cURL)

與常規客戶端工具(詳見 /guides/claude-tool-use-basics)最大的區別在於:使用 MCP Connector 時,你需要在請求體頂層傳 mcp_servers 定義連接資訊,再在 tools 數組裏用 mcp_toolset 引用該伺服器的 name。

按官方文檔整理的 Python SDK 最小調用示例:

python
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "幫我查一下當前遠程服務裏有哪些可用工具,並查詢最新一條工單狀態。"}
    ],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "ticket-mcp",
            "authorization_token": "YOUR_OAUTH_BEARER_TOKEN",
        }
    ],
    tools=[
        {
            "type": "mcp_toolset",
            "mcp_server_name": "ticket-mcp",
        }
    ],
    betas=["mcp-client-2025-11-20"],
)

print(response.content)

對應的原生 cURL 請求頭與核心結構如下:

bash
curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "查詢最新工單狀態"}],
    "mcp_servers": [{
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "ticket-mcp",
      "authorization_token": "YOUR_OAUTH_BEARER_TOKEN"
    }],
    "tools": [{"type": "mcp_toolset", "mcp_server_name": "ticket-mcp"}]
  }'

同一條請求裏可以配置多個遠程 MCP 伺服器,只要每個條目在 mcp_servers 裏的 name 唯一,並在 tools 裏各自配一條對應的 mcp_toolset 即可,也可以和普通自定義工具或聯網搜尋工具混用。

二、認證方式與工具白名單過濾

把遠程 MCP 接進生產接口時,有兩項配置不能省:

1. Bearer 令牌認證(authorization_token)

大多數遠程業務 MCP 伺服器都受 OAuth 或 API 密鑰保護。你在 mcp_servers 條目裏填入 authorization_token 後,Anthropic 服務端向該 URL 發起請求時會自動帶上 Authorization: Bearer <token> 請求頭。注意,MCP Connector 本身不替你跑瀏覽器 OAuth 跳轉或刷新過期令牌,你的應用後端需要先拿好有效訪問令牌再傳給 Messages API。

2. 用 default_config 與 configs 控制暴露哪些工具

一個成熟的第三方 MCP 伺服器動輒暴露二三十個增刪改查工具,全量掛載既浪費輸入 token,又有誤觸寫操作的風險。官方推薦在 mcp_toolset 中用「預設全關 + 顯式白名單」的寫法:

json
{
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "ticket-mcp",
      "default_config": {
        "enabled": false,
        "defer_loading": true
      },
      "configs": {
        "list_tickets": { "enabled": true },
        "get_ticket_detail": { "enabled": true }
      }
    }
  ]
}
  • 白名單模式:設 default_config.enabled 為 false,只在 configs 裏把只讀或安全工具設為 enabled: true;
  • 黑名單模式:保持預設啟用,只在 configs 裏把高危刪除工具設為 enabled: false;
  • 按需延遲加載(defer_loading):開啟後可避免在開局一次性加載冗長的工具 Schema,適合掛載大型工具集的場景。
Claude 會員充值與成品號提示:國內銀行卡在結帳頁被拒時,可通過本站支付寶、微信支付或 AlipayHK 獲取 iOS 訂閱卡密自助開通 Claude Pro 或高配額 Claude Max(全程無需上號交密碼);需要現成帳號可了解 Claude Pro 成品號 與 Claude Max 5x 成品號(注:Anthropic 消費者條款禁止共享轉讓帳號且違規可終止無退款,成品號均明確標註不質保封號)。

三、響應結構怎麼讀與常見報錯排查

請求返回後,響應的 content 數組裏會出現兩類專門針對 MCP 的內容塊,無需你的客戶端再去跑工具回傳:

  • mcp_tool_use:記錄 Claude 決定調用哪個伺服器(server_name)、哪個工具(name)以及傳入的參數(input);
  • mcp_tool_result:記錄遠程 MCP 伺服器返回的執行結果或報錯訊息(is_error),緊接着 Claude 會基於結果生成最終的 text 回覆。

MCP Connector 調用報錯或工具不生效排查

圖:本站根據 Claude 官方文檔:MCP connector 整理的示意圖

如果聯調報錯(通用狀態碼對照見 /guides/claude-api-error-codes),優先核對以下四條官方限制:

  1. 只支持 Tools 原語:MCP 規範裏的 Resources(資源讀取)和 Prompts(提示模板)目前不會通過 API 的 MCP Connector 暴露;
  2. 必須是公網可達 HTTPS:不能填 localhost、127.0.0.1 或本地命令行 npx 啟動的 stdio 服務;內網服務若要接入,需走安全網關或官方受控隧道方案;
  3. 檢查 Beta 頭拼寫:漏傳 mcp-client-2025-11-20 或拼錯名稱,API 會直接報參數不識別(400 invalid_request_error);
  4. 計費說明:MCP Connector 本身不收額外功能費,但遠程伺服器返回的工具描述和 mcp_tool_result 內容都會計入標準輸入輸出 token。如果團隊日常更多是在本地終端用現成的編程代理調 MCP,直接開通 Claude Code 訂閱服務 會比自己手寫一套 API 工具鏈省事得多。

常見問題

問:MCP Connector 需要我的客戶端收到 mcp_tool_use 後自己去請求遠程伺服器嗎?

答:不需要。只要是配在 mcp_servers 裏的遠程伺服器,Anthropic 服務端會在單次 API 調用內部自動完成工具列表拉取和遠程執行,直接把結果拼好返回給你。

問:能不能在 Amazon Bedrock 或 Google Vertex AI 上用這個 MCP Connector?

答:官方Availability 說明中,服務端直連的外部網絡類工具在不同雲託管平台的支持進度與原生 Claude API(api.anthropic.com)存在差異,跨雲調用前請先查核官方文檔頂部的平台支持表。

問:多輪對話時,歷史消息裏的 mcp_tool_use 和 mcp_tool_result 要怎麼傳回下一輪?

答:和普通多輪 Messages 調用一樣,直接把上一輪助手返回的完整 response.content 原樣追加進 messages 歷史列表即可,不要手動刪改其中的工具調用塊。

問:人在國內沒有外幣信用卡,怎麼訂閱或升級 Claude 付費套餐?

答:可在本站 AI 會員充值總覽頁 選擇 Claude Pro 自助充值 或 Claude Max 充值,付款後即時發卡密、24 小時自助兌換且可開具增值稅發票;實時價格與售後邊界(含封號不質保)以商品頁當天展示為準。

相關教學

參考資料

  • Claude 開發者平台文檔:MCP connector — https://platform.claude.com/docs/en/agents-and-tools/mcp-connector

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同產品的其他教學

  1. 01

    Anthropic Contextual Retrieval(上下文增強檢索)是什麼、怎麼實現:給文檔塊自動補背景摘要結合緩存降失誤率

    長文檔切成小塊後丟了公司名、年份和主語指代導致 RAG 頻頻搜錯?本文按 Anthropic 官方技術文章詳解 Contextual Retrieval 原理、官方公開評測失誤率下降 49% 至 67% 的組合架構,以及用 Claude 提示詞緩存低成本批量生成切片背景的完整 Python 代碼。

    Claude其他 AI 工具0
  2. 02

    RAG 知識庫回答不準怎麼調優:切片大小(Chunking)、BM25 + 向量混合檢索與 Rerank 重排序三步排查法

    搭好的 RAG 企業知識庫一問具體型號、報錯碼或跨行表格就答非所問?本文按 OpenAI 與 Anthropic 官方檢索文檔,給出先隔離檢索與生成故障、再按結構化切片(Chunking)、BM25 加向量混合召回(RRF)與 Rerank 重排序逐層調優的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 開源本地部署(Docker Compose)與提示詞版本管理(Prompt Management)從零上手教學

    企業內網嚴禁業務日誌出境,又想免費擁有大模型調用鏈追蹤與不發版熱更新提示詞的能力?本文按 Langfuse 官方文檔整理 Docker Compose 本地一鍵啟動(含 ClickHouse 架構注意事項)、密鑰配置與 Prompt Management 標籤化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入門教學:給 LangGraph 與原生 OpenAI / Claude 接口加調用鏈追蹤、Token 成本統計與免費層限額

    智能體多步調用總是找不到哪一輪提示詞跑偏、單次請求到底燒了多少 Token?本文按 LangSmith 官方文檔講清環境變量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 與 @traceable 追蹤原生接口,以及 Developer 免費層額度與留存規則。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效讀英文文獻:PDF 翻譯插件、批註導出精讀與防捏造參考文獻流程

    在 Zotero 裏讀英文頂會論文怎麼無縫聯動 Claude 與 ChatGPT?本文整理 Translate for Zotero 劃詞翻譯配置、高亮批註導出精讀提示詞,以及杜絕 AI 捏造假 DOI 參考文獻的核驗閉環。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 與本地 Ollama 做個人雙鏈筆記問答:主流插件配置與私隱脫敏邊界

    想在 Obsidian 裏基於自己的雙鏈筆記庫做 AI 問答又擔心私隱外泄?本文對比 Copilot 與 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 與本地 Ollama 的步驟及敏感目錄隔離規則。

    Claude其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~