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 条评论

登录 后参与评论

还没有评论,来抢沙发~