结论先说
- 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 条评论
还没有评论,来抢沙发~