MCP协议开发实战：从零搭建AI Agent工具链，TaoToken统一Key打通JSON-RPC调用-北京尧图网络

1. 为什么你的 AI Agent 总是接不上工具MCP 协议到底解决了什么如果你写过 AI Agent大概率遇到过这种局面给模型接一个查天气的工具写一套函数签名接一个数据库查询再写一套换个模型厂商函数调用格式又变了之前写的胶水代码全部推倒重来。工具越多维护成本越高最后 Agent 项目变成一堆 if-else 和适配层。MCPModel Context Protocol模型上下文协议就是冲着这个痛点来的。它做的事情本质上是给「AI 应用」和「外部工具/数据源」之间定了一套标准插座。你可以把它类比成 USB-C以前每个设备一个充电口现在统一了谁都能插。MCP 用 JSON-RPC 2.0 作为通信底座把工具Tools、资源Resources、提示词Prompts抽象成标准能力Server 负责暴露能力Client 负责调用能力中间走统一的请求-响应格式。这套协议适合谁三类人最该关注。第一类是正在做 AI Agent 产品的开发者工具链越复杂收益越大第二类是想把自己内部系统比如工单、监控、知识库暴露给 AI 的团队MCP Server 写一次多个客户端都能用第三类是折腾本地编码助手的人Claude Code、Cline 这类工具已经原生支持 MCP配好就能让模型直接调你的工具。但光有协议还不够。实际开发里你很快会撞上第二个问题Agent 要调用大模型来决策而模型 API 的 Key 管理、多模型切换、额度统计又是一摊事。我这次的做法是把模型调用统一收口到 TaoToken用它的统一 Key 打通 JSON-RPC 调用链路MCP Server 只管工具模型推理走统一入口。下面从零把这条链跑通每一步都给可复制的配置。2. TaoToken 前置准备统一 Key 与 MCP 工具链的接入定位在动手写 Server 之前先把模型侧的入口理清楚。MCP 协议本身不负责模型推理它只负责「工具怎么被调用」。真正决定 Agent 行为的是背后那个大模型。所以整条链路是这样的AI AgentClient→ 通过 MCP 协议发现并调用工具 → 工具执行结果回传给模型 → 模型继续推理。而模型这一环我用 TaoToken 的统一 Key 来承接。TaoToken 在这里的角色是「模型调用的统一网关」。你不需要为每个模型厂商单独维护一套 Key 和 SDK拿一个 Key配好 Base URL就能在 OpenAI 兼容的接口下调不同模型。对 MCP 工具链来说这意味着你的 Agent 在决定调用哪个工具、传什么参数时走的是同一套模型接口切换模型只改一个 Model ID。具体要准备三样东西我把它叫「三件套」配置项值说明Base URLhttps://taotoken.net/apiOpenAI 兼容接口地址不加任何多余路径API Key在控制台创建统一 Key多模型共用Model ID按需选择例如对话模型、编码模型分别指定获取 Key 的入口在控制台的 API Keys 页面创建后复制保存后面写进环境变量。如果你还没账号从官网进https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台生成 Key。这里有个容易踩的坑很多人把 Base URL 写成带/v1的完整路径结果请求 404。TaoToken 的接口地址就是https://taotoken.net/apiSDK 内部会自己拼/chat/completions这类路径。你在 OpenAI SDK 里配置base_url时填这个根地址即可。另外MCP 的工具调用和模型调用是两条独立的链路别混在一起。MCP Server 监听的是本地 stdio 或 SSE模型请求走的是 HTTPS。两者通过 Agent 的编排逻辑串起来Agent 拿到用户问题 → 请求模型 → 模型返回「我要调用某工具」→ Agent 通过 MCP Client 调工具 → 结果再喂回模型。理解这个分层后面排错会快很多。环境上我建议 Node.js 18 或 Python 3.10两个官方 SDK 都维护得不错。本文用 Node.js 演示因为modelcontextprotocol/sdk的 TypeScript 类型提示对工具参数定义很友好。装依赖前先确认node -v输出不低于 18否则部分 ESM 特性会报错。3. 可复制配置MCP Server 工具注册与 JSON-RPC 调用参数这一节是核心直接给能跑的代码和配置。先建项目mkdir mcp-agent-demo cd mcp-agent-demo npm init -y npm install modelcontextprotocol/sdk zod npm install -D typescript tsx types/node然后在package.json里加上type: module避免 ESM 导入报错。接着创建tsconfig.json{ compilerOptions: { target: ES2022, module: ES2022, moduleResolution: bundler, strict: true, esModuleInterop: true, skipLibCheck: true, outDir: dist }, include: [src/**/*.ts] }现在写 MCP Server。创建src/server.ts注册两个工具一个计算器一个查询当前时间。工具参数用 zod 定义SDK 会自动转成 JSON Schema 暴露给 Client。import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; const server new McpServer({ name: demo-tools, version: 1.0.0, }); // 工具一加法计算器 server.tool( add_numbers, 计算两个数字之和, { a: z.number().describe(第一个加数), b: z.number().describe(第二个加数), }, async ({ a, b }) { return { content: [{ type: text, text: 结果${a b} }], }; } ); // 工具二获取当前时间 server.tool( get_current_time, 返回服务器当前时间, {}, async () { return { content: [{ type: text, text: new Date().toISOString() }], }; } ); const transport new StdioServerTransport(); await server.connect(transport); console.error(MCP Server 已启动等待 JSON-RPC 请求);注意最后一行用console.error而不是console.log。stdio 传输模式下stdout 是 JSON-RPC 的专用通道你往里打日志会污染协议消息Client 直接解析失败。这个坑我第一次写的时候踩得很实排查了半天才发现是日志串了通道。Server 写好了接下来是 Client 侧连接配置。如果你用 Claude Code 或 Cline 这类支持 MCP 的客户端配置通常是一个 JSON 文件。以 Claude Code 为例在项目根目录创建.mcp.json{ mcpServers: { demo-tools: { command: npx, args: [tsx, src/server.ts], env: { TAOTOKEN_API_KEY: 你的统一Key, TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_MODEL: 你的ModelID } } } }这里把三件套通过env注入Server 或后续的 Agent 逻辑都能读到。如果你用的是 Cline 的 MCP 配置结构类似把command和args填对即可。Codex 的auth.json场景下模型侧凭证单独放MCP 的 Server 配置走各自的 settings 文件两者不要混写。再给一个 Agent 侧调用模型的配置片段用 OpenAI SDK 指向 TaoTokenimport OpenAI from openai; const client new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }); const resp await client.chat.completions.create({ model: process.env.TAOTOKEN_MODEL!, messages: [{ role: user, content: 帮我算一下 12 加 30 }], tools: [ { type: function, function: { name: add_numbers, description: 计算两个数字之和, parameters: { type: object, properties: { a: { type: number }, b: { type: number }, }, required: [a, b], }, }, }, ], });这段代码里tools的定义和 MCP Server 里注册的工具是对应的。实际生产中你可以从 MCP Client 的listTools结果动态生成这份 schema避免手写两份。这就是 MCP 的价值工具定义只写一次模型调用和协议调用共享同一份描述。4. 验证请求本地联调与 JSON-RPC 成功结果确认配置写完必须验证。分两步先确认 MCP Server 本身能被连上、工具能列出再确认模型侧通过 TaoToken 能正常返回工具调用意图。第一步用官方提供的调试方式手动跑一次 Server。启动npx tsx src/server.ts进程会挂起等待输入这是正常的因为 stdio 在等 JSON-RPC 消息。更直观的方式是写一个最小 Client 来连它。创建src/client.tsimport { Client } from modelcontextprotocol/sdk/client/index.js; import { StdioClientTransport } from modelcontextprotocol/sdk/client/stdio.js; const transport new StdioClientTransport({ command: npx, args: [tsx, src/server.ts], }); const client new Client({ name: test-client, version: 1.0.0 }); await client.connect(transport); const tools await client.listTools(); console.log(可用工具, JSON.stringify(tools, null, 2)); const result await client.callTool({ name: add_numbers, arguments: { a: 12, b: 30 }, }); console.log(调用结果, JSON.stringify(result, null, 2)); await client.close();运行npx tsx src/client.ts你应该看到类似输出{ tools: [ { name: add_numbers, description: 计算两个数字之和, inputSchema: { ...: ... } }, { name: get_current_time, description: 返回服务器当前时间, inputSchema: { type: object } } ] }调用结果里content数组会返回结果42。看到这个说明 JSON-RPC 的请求-响应链路通了工具注册和参数传递都没问题。第二步验证模型侧。写一个脚本把用户问题发给 TaoToken看模型是否返回tool_callsconst resp await client.chat.completions.create({ model: process.env.TAOTOKEN_MODEL!, messages: [{ role: user, content: 12 加 30 等于多少用工具算 }], tools: [/* 同上 */], }); const choice resp.choices[0]; if (choice.finish_reason tool_calls) { console.log(模型请求调用, choice.message.tool_calls); } else { console.log(模型直接回答, choice.message.content); }如果返回finish_reason: tool_calls并且tool_calls[0].function.name是add_numbers参数是{a:12,b:30}那整条链路就闭环了。接下来 Agent 拿到这个调用意图通过 MCP Client 执行工具把结果作为tool角色消息再发回模型模型给出最终自然语言回答。实测下来从 Server 启动到模型返回工具调用整个流程在本地几百毫秒内完成。如果你想让 Agent 更聪明可以在系统提示里写清楚每个工具的用途模型选择工具的准确率会明显提升。5. 本篇常见报错排查401、local proxy failed 与 reading choices跑通之前报错是常态。我把这次遇到的几个典型问题和解法列出来对照着查能省不少时间。401 Unauthorized。这个最常见基本是 Key 的问题。检查三点环境变量TAOTOKEN_API_KEY是否真的注入到了进程里echo $TAOTOKEN_API_KEY确认Key 有没有多余空格或换行Base URL 是不是写成了https://taotoken.net/api/v1这种带后缀的。TaoToken 的地址就是https://taotoken.net/apiSDK 自己拼路径。如果还报 401去控制台确认 Key 是否被禁用或额度耗尽。local proxy failed / connection refused。这个报错通常出现在 MCP Client 连 Server 的时候。原因一般是command或args写错比如npx tsx找不到文件或者工作目录不对。检查.mcp.json里的路径是不是相对于项目根目录tsx有没有装成依赖。另一个可能是 Server 启动就崩了比如 TypeScript 编译错误但错误信息被 stdio 吞了。这时候单独跑npx tsx src/server.ts看 stderr 有没有报错。reading choices of undefined。这个报错来自模型响应解析。resp.choices是 undefined说明请求根本没成功返回标准结构。常见原因是 Base URL 配错请求打到了错误地址返回了一个非 OpenAI 格式的响应体。也可能是 Model ID 填错服务端返回了错误对象。打印完整的resp或捕获异常看error.message一般能定位。还有一种情况是网络层被拦截但这类问题不在本文讨论范围确认你的请求地址是https://taotoken.net/api即可。OAuth 相关报错。如果你在 Claude Code 里配置 MCP 时看到 OAuth 字样多半是客户端把 MCP Server 当成了需要 OAuth 的远程服务。本地 stdio 模式的 Server 不需要 OAuth检查配置里有没有误加url字段。stdio 和 SSE 是两种传输方式本地进程用 stdio远程用 SSE别混。工具调用参数类型不匹配。模型返回的参数是字符串12但你的 zod schema 定义的是z.number()Server 会校验失败。解法是在 schema 里用z.coerce.number()做强制转换或者在 Agent 侧做一次参数清洗。这个在模型能力较弱时特别容易出现。排查的核心思路是分层先确认 MCP Server 单独能跑再确认模型请求单独能通最后确认两者串联。哪一层报错就查哪一层不要一上来就怀疑整条链路。6. 把工具链接进真实项目从 demo 到可维护的 Agent 工具链demo 跑通只是起点。真实项目里工具会越来越多参数会越来越复杂这时候几件事必须提前做。第一工具描述要写清楚。模型选工具靠的是description和参数的describe。我见过太多人写「查询数据」四个字模型根本不知道查什么数据、什么时候该用。把工具名写成动词开头的短语描述里写清楚输入输出和适用场景模型的选择准确率会高一个档次。第二错误处理要统一。MCP 工具执行失败时不要直接抛异常让进程崩掉而是返回一个带isError: true的结果让模型知道工具失败了它可以决定重试还是换工具。这样 Agent 的鲁棒性会好很多。第三模型调用统一走 TaoToken 的好处在这里体现出来。你的工具链可能同时需要对话模型做意图理解、编码模型做代码生成如果每个模型单独配 Key管理成本很高。统一 Key 之后切换模型只改一个 Model ID额度统计也集中在一处。对于长期跑的 Agent 服务这种收口能省掉大量运维精力。如果你打算把 Agent 做成长期运行的服务建议了解一下 Coding Plan 这类方案适合需要持续调用模型、跑编码或 Agent 任务的场景。入口在 https://taotoken.net/api-keys 先把 Key 管起来再按需选模型。最后说一个实用技巧MCP Server 的工具列表是可以动态生成的。你可以从数据库表结构、内部 API 文档自动生成工具定义这样新增一个接口就自动多一个工具不用手写。配合统一的模型入口整条工具链的扩展成本会低很多。跑通本文的 demo 后试着把你手头一个真实的内部查询接口包成 MCP 工具接进 Agent 里你会对这套协议的价值有更直接的感受。

MCP协议开发实战：从零搭建AI Agent工具链，TaoToken统一Key打通JSON-RPC调用

相关推荐

oneapi私有化部署报failed to get gpt-3.5-turbo token encoder：把endpoint改到TaoToken的排查清单

AnyPS5技术拆解：从协议转换到终端适配的串流架构实践

Codex CLI 0.153.2 落地 CI 流水线：从认证失效到沙箱逃逸的三次排查实录｜TaoToken 统一 Key 通道实践

更多资讯

初创企业建站选型实测：BBWEYY、Codex＋亚马逊AWS、比文云与Dreamweaver的低成本验证与上线速度对比（含TaoToken统一Key接入）

AI日报制作全流程：从信息采集到深度解读的实操指南

ESP8266开关控制负载：GPIO驱动与安全隔离实战指南

AI日报自动化工作流：四层漏斗架构设计与实操

计算机总线全解析：从芯片内部到PCIe，搞懂I²C/SPI/AMBA的定位与选型

SpringSecurity自定义登录页与请求：SSM项目实战配置指南

今日更新

Susi AI API实战指南：susi_alexa_skill如何用Node.js调用chat.json获取智能回答

换新电脑了？KeyStats 恢复码数据找回完全指南，端到端加密统计一键重建

重建二叉树：由前序与中序遍历序列还原二叉树的原理与 Java 实现（YCBlogs 剑指 Offer 精讲）

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？