Claude Agent SDK 怎麼掛載 MCP 伺服器與自定義內聯工具(createSdkMcpServer)

在 Claude Agent SDK 裏想接外部 MCP 服務,或者直接把自己的業務函數暴露成工具怎麼寫?本文按官方文檔整理 mcpServers 配置、createSdkMcpServer 內聯工具(TS/Python)與 mcp__ 權限放行寫法。

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

結論先說

  1. Agent SDK 擴展工具有兩條路:現成的第三方服務通過 mcpServers 掛載外部 stdio 或遠程 HTTP 伺服器;你自己的業務函數用 createSdkMcpServer(Python 為 create_sdk_mcp_server)寫成同進程內聯工具。
  2. 內聯工具零子進程開銷且共享內存:它直接跑在你的 Node.js 或 Python 主進程裏,能直接拿主程序的數據庫連接池、登入態上下文幹活。
  3. 掛上去不等於自動放行:所有 MCP 工具都會被自動重命名為 mcp__<伺服器鍵名>__<工具名>,無人值守運行時必須把這個完整名字(或伺服器通配符)寫進 allowedTools。
  4. Python 跑內聯工具要用 ClaudeSDKClient(或異步生成器輸入):因為同進程工具回調需要雙向通信通道,不能只給 query() 傳純靜態字符串提示詞。
  5. Claude Code 訂閱與高配額開通入口:國內無境外卡可通過本站 iOS 免上號自助卡密開通 Claude Pro 會員 或 5 倍以上額度的 Claude Max 會員,完整檔位選型見 Claude Code 訂閱說明頁。

外部 MCP 與內聯 SDK 工具對比

圖:本站根據 Claude Agent SDK 官方文檔:Custom tools 與《MCP》整理的示意圖

本文根據 Claude Code 官方文檔《Connect to MCP servers in the SDK》《Custom tools》《Agent SDK overview》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Anthropic 官方網站。

適用於誰

  • 搜「claude agent sdk mcp 工具」「createSdkMcpServer 怎麼用」,想給智能體加上查內部數據庫、調微服務接口能力的開發者;
  • 覺得為了兩三個簡單函數專門起一個獨立 MCP 子進程太重,想直接在主程序內存裏寫內聯工具的人;
  • 掛上 MCP 伺服器後模型看得到工具卻一直卡權限調用失敗,不知道 allowedTools 該怎麼寫前綴的人。

如果你是第一次接觸這套開發包,建議先閱讀 Claude Agent SDK 入門:是什麼、怎麼裝、第一個智能體;獨立標準 MCP 伺服器的寫法可對比 MCP Server 開發入門(Python)。

一、掛載外部 MCP 伺服器(本地 stdio 與遠程 HTTP)

配置結構與命令行裏的 .mcp.json 基本同源(命令行側語法見 Claude Code MCP 配置教學)。在 query() 的 options.mcpServers(Python 為 mcp_servers)裏,你可以同時掛載本地子進程和帶鑑權頭的遠程 HTTP 端點:

typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const msg of query({
  prompt: "讀取 docs 目錄結構,並查詢線上工單列表",
  options: {
    mcpServers: {
      fs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "./docs"],
      },
      tickets: {
        type: "http",
        url: "https://mcp.example.com/mcp",
        headers: {
          Authorization: `Bearer ${process.env.TICKET_API_TOKEN}`,
        },
      },
    },
    // 放行 fs 下的指定工具,以及 tickets 伺服器的全部工具
    allowedTools: ["mcp__fs__list_directory", "mcp__fs__read_file", "mcp__tickets"],
  },
})) {
  if (msg.type === "result") console.log(msg.subtype);
}

如果倉庫根目錄已經有維護好的 .mcp.json,不想在代碼裏再抄一遍,也可以通過配置 settingSources: ["project"] 讓 SDK 啟動時讀取項目配置。

二、用 createSdkMcpServer 編寫同進程自定義內聯工具

編寫內聯 SDK 工具四步流程

圖:本站根據 Claude Agent SDK 官方文檔:Custom tools 整理的示意圖

當你只想讓智能體查一下訂單表或發一條內部飛書通知時,使用內聯 SDK MCP 最輕便。

1. TypeScript 寫法(搭配 zod 校驗參數)

先安裝 zod,用 tool() 定義名稱、說明、參數 Schema 和處理函數,再用 createSdkMcpServer() 打包:

typescript
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const lookupOrder = tool(
  "lookup_order",
  "按訂單號查詢當前訂單支付狀態與金額",
  { orderId: z.string().describe("以 ORD 開頭的訂單編號") },
  async ({ orderId }) => {
    // 這裏可直接調用主進程裏的 Prisma / 數據庫連接池
    const mockStatus = { orderId, status: "PAID", amount: "99.00" };
    return {
      content: [{ type: "text", text: JSON.stringify(mockStatus) }],
    };
  }
);

const billingServer = createSdkMcpServer({
  name: "billing-service",
  version: "1.0.0",
  tools: [lookupOrder],
});

for await (const msg of query({
  prompt: "幫我查一下訂單 ORD-20261118 的狀態",
  options: {
    mcpServers: { billing: billingServer },
    allowedTools: ["mcp__billing__lookup_order"],
  },
})) {
  if (msg.type === "result") console.log("執行完成");
}

看清上面 allowedTools 裏的名字:雖然 createSdkMcpServer 內部 name 寫了 "billing-service",但掛載進 mcpServers 對象時用的鍵名是 billing,因此最終工具全名是 mcp__billing__lookup_order。

2. Python 寫法(搭配 @tool 與 ClaudeSDKClient)

Python 端使用 @tool 裝飾器聲明參數字典,並通過 ClaudeSDKClient 發起會話:

python
import asyncio
from typing import Any
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, create_sdk_mcp_server, tool

@tool("lookup_order", "按訂單號查詢訂單狀態", {"order_id": str})
async def lookup_order(args: dict[str, Any]) -> dict[str, Any]:
    oid = args["order_id"]
    return {
        "content": [{"type": "text", "text": f"訂單 {oid} 當前狀態:已支付"}]
    }

billing_server = create_sdk_mcp_server(
    name="billing",
    version="1.0.0",
    tools=[lookup_order],
)

async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"billing": billing_server},
        allowed_tools=["mcp__billing__lookup_order"],
    )
    async with ClaudeSDKClient(options=options) as client:
        await client.query("幫我查一下訂單 ORD-8899 的支付情況")
        async for msg in client.receive_response():
            print(msg)

asyncio.run(main())
Claude Code 額度與成品號準備提示:長倉庫重構、子代理並行與高頻工具調用較消耗 5 小時與每週配額。自有帳號免密自助續費可看 Claude Pro 自助充值 與 Claude Max 充值頁;若尚未註冊帳號,也可了解 Claude Pro 成品號 或 Claude Max 5x 成品號(按 Anthropic 消費者條款禁止共享帳號且違規可終止無退款,成品號均明確標註不質保封號)。

三、權限命名規則與常見避坑要點

很多開發者代碼能跑起來,但模型一到調用自定義工具時就被靜默攔截,問題幾乎都出在權限字段與返回結構上:

配置寫法作用範圍適用場景
mcp__billing__lookup_order只預批准該伺服器下的單個指定工具讀寫混合伺服器,只自動放行查詢接口
mcp__billing 或 mcp__billing__*預批准 billing 鍵名下的全部工具純只讀內部查詢服務,整組免審放行
disallowedTools: ["mcp__fs__write_file"]強制屏蔽第三方 MCP 裏的危險寫工具接入現成開源伺服器但只允許讀取能力

此外還有三個容易踩的細節:

  1. 返回結果必須符合 MCP 內容塊數組格式:無論是 TypeScript 還是 Python,工具處理函數的返回值都要包在 content: [{ type: "text", text: "..." }] 裏;直接裸返回一個普通字符串或數字會導致協議序列化報錯,建議把複雜 JSON 對象先 JSON.stringify 轉成格式化文本再返回。
  2. 混合使用內置工具與自定義工具:如果你希望智能體先調你的 lookup_order 查出異常訂單,再自己去代碼庫裏搜對應報錯邏輯,記得把內置的 "Read"、"Grep"、"Glob" 和 "mcp__billing__lookup_order" 一起放進 allowedTools 數組。
  3. 控制工具數量防上下文膨脹:當掛載的外部與內聯 MCP 工具加起來超過幾十個時,每次請求攜帶的 Schema 會顯著拉高輸入開銷,應按業務職責拆分成專職小智能體按需掛載。

關於運行憑證:Agent SDK 服務端調用使用開發者控制檯簽發的密鑰計費(創建與限額說明見 Claude API Key 怎麼獲取);若你是在本地終端用交互式命令行調試日常項目,想搭配個人訂閱使用,可參考本站 Claude Code 訂閱充值頁。

常見問題

問:工具函數內部拋異常崩潰了,會導致整個智能體進程退出嗎?

答:建議在工具異步函數內部自己 try / catch 業務異常,失敗時返回 { content: [{ type: "text", text: "查詢失敗:原因..." }], isError: true },這樣模型能讀懂報錯並決定重試還是如實告知用戶,而不是直接中斷循環。

問:掛載了十幾個內聯工具,會不會把上下文塞滿?

答:每個工具的名稱、描述與參數 JSON Schema 都會佔用系統上下文,且描述寫得越含糊模型越容易選錯工具。建議只掛載當前業務鏈路真正需要的工具,並把每個參數說明寫清楚。

問:怎麼確認外部 MCP 伺服器在 SDK 裏到底有沒有握手成功?

答:監聽 query() 返回的第一條 type === "system" 且 subtype === "init" 的初始化消息,裏面的 mcp_servers 數組會列出每個掛載伺服器的 name 與連接 status(如 connected 或 failed),可在啟動階段記錄告警日誌。

問:國內沒有海外銀行卡,怎麼給 Claude Code 開通 Pro 或 Max 訂閱?

答:可在 Claude Code 訂閱頁 選擇走 iOS 訂閱鏈路的 Claude Pro 自助卡密 或 Claude Max 充值,支持支付寶、微信支付與 AlipayHK,無需交出帳號密碼;若帳號彈出身份核驗也可查看 Claude KYC 認證人工協助(失敗不收費,封號不在質保範圍)。

相關教學

參考資料

  • Claude Agent SDK 官方文檔:Connect to MCP servers in the SDK — https://code.claude.com/docs/en/agent-sdk/mcp
  • Claude Agent SDK 官方文檔:Custom tools — https://code.claude.com/docs/en/agent-sdk/custom-tools
  • Claude Agent SDK 官方文檔:Overview — https://code.claude.com/docs/en/agent-sdk/overview

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 條評論

登入 後參與評論

還沒有評論,來搶沙發~