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

圖:本站根據 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 編寫同進程自定義內聯工具

圖:本站根據 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 裏的危險寫工具 | 接入現成開源伺服器但只允許讀取能力 |
此外還有三個容易踩的細節:
- 返回結果必須符合 MCP 內容塊數組格式:無論是 TypeScript 還是 Python,工具處理函數的返回值都要包在
content: [{ type: "text", text: "..." }]裏;直接裸返回一個普通字符串或數字會導致協議序列化報錯,建議把複雜 JSON 對象先JSON.stringify轉成格式化文本再返回。 - 混合使用內置工具與自定義工具:如果你希望智能體先調你的
lookup_order查出異常訂單,再自己去代碼庫裏搜對應報錯邏輯,記得把內置的"Read"、"Grep"、"Glob"和"mcp__billing__lookup_order"一起放進allowedTools數組。 - 控制工具數量防上下文膨脹:當掛載的外部與內聯 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 入門:是什麼、怎麼裝、第一個智能體
- Claude Code MCP 配置教學:claude mcp add、配置文件位置與常用 MCP
- MCP Server 開發入門(Python):用官方 SDK 寫第一個伺服器
- Claude API Key 怎麼獲取:Claude Console 創建密鑰與用量查看
參考資料
- 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
0 條評論
還沒有評論,來搶沙發~