1. 从一次 JSON-RPC 调用失败说起MCP 工具链到底卡在哪如果你正在做 AI Agent 工具链大概率遇到过这种场景本地 MCP Server 明明跑起来了Cursor 或 Claude Desktop 里也能看到工具列表但一到真正调用就报local proxy failed或者reading choices之类的错。更让人头疼的是你手里可能同时有 OpenAI、Claude、Gemini 三套 Key每接一个客户端就要重新配一遍 Base URL 和模型名改到最后自己都记不清哪个 Key 对应哪个 endpoint。MCPModel Context Protocol本身并不复杂底层就是 JSON-RPC 2.0一次tools/call请求发出去Server 执行完把结果塞回content数组里。真正麻烦的是“工具链”这三个字——它意味着你要把模型调用、MCP Server、客户端配置、鉴权这几段串起来任何一段的 endpoint 或 Key 写错整条链路就断。这篇内容面向的是已经写过一点 MCP Server、但还没把整条链路跑顺的开发者。我会用一个天气查询 MCP Server 作为最小案例把 JSON-RPC 的请求响应、TaoToken 统一 Key 的 endpoint 填写、以及一次完整的工具调用验证动作全部走一遍。你跟着做完应该能得到一个能被 Cursor 或 Claude Code 正常调用的 MCP 工具并且知道每一段出错时该看哪里。先说清楚 TaoToken 在这条链路里的位置它是一个兼容 OpenAI 接口规范的模型调用入口你拿一个 Key 就能访问多种模型省去为每个客户端单独申请和切换 Key 的麻烦。MCP Server 负责暴露工具TaoToken 负责提供模型推理能力两者通过客户端Cursor、Claude Code 等串起来。下面从环境准备开始。2. TaoToken 前置准备统一 Key 与 endpoint 怎么填在写 MCP Server 之前先把模型调用这一段打通否则后面调试工具调用时你分不清是 MCP 的问题还是模型鉴权的问题。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 使用。官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册和查看文档都从这里进。拿到 Key 之后第一件事是确认它能正常调用模型。我用 curl 做一次最小验证这样不依赖任何 SDK能最快定位问题curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复ok}], max_tokens: 10 }如果返回里能看到choices数组和正常的content说明 Key 和 endpoint 都没问题。这里有个细节Base URL 填https://taotoken.net/api具体路径由 SDK 自己拼/v1/chat/completions不要手动把/v1写进 Base URL否则会出现双斜杠或路径重复。接下来是模型 ID 的确认。TaoToken 支持多种模型你在请求体里填的model字段要和平台文档里列出的 ID 完全一致。常见的有gpt-4o-mini、claude-3-5-sonnet这类具体以你账号下可用的为准。如果你在 Cursor 里配置模型名要填在 Cursor 的模型设置里如果在 Claude Code 里用则通过环境变量或配置文件指定。对于 MCP 工具链来说模型调用和 MCP Server 是两条独立的线。模型负责“决定调用哪个工具、生成什么参数”MCP Server 负责“执行工具、返回结果”。所以先把模型这条线用 curl 验证通过再去写 MCP Server排障时会清晰很多。我试过在没验证模型的情况下直接调 MCP结果报了一堆reading choices的错最后发现是 Key 里多了一个空格。3. 可复制配置MCP Server 与客户端 settings 片段这一节给出可以直接复制的配置。先看 MCP Server 侧。我用 Node.js 写一个最小的天气查询 Server依赖官方 SDKmkdir weather-mcp cd weather-mcp npm init -y npm install modelcontextprotocol/sdk创建server.js核心是注册tools/list和tools/call两个 handlerimport { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new Server( { name: weather-mcp, version: 1.0.0 }, { capabilities: { tools: {} } } ); server.setRequestHandler(tools/list, async () ({ tools: [{ name: getWeather, description: 查询指定城市当前天气, inputSchema: { type: object, properties: { city: { type: string, description: 城市名称 } }, required: [city] } }] })); server.setRequestHandler(tools/call, async (req) { if (req.params.name getWeather) { const city req.params.arguments.city; return { content: [{ type: text, text: ${city}今天晴32℃ }] }; } throw new Error(Unknown tool); }); const transport new StdioServerTransport(); await server.connect(transport);注意console.error可以用于日志但绝对不能用console.log因为 stdio 模式下 stdout 是 JSON-RPC 的通道混入普通文本会直接破坏协议客户端会报解析失败。然后是客户端配置。Cursor 的 MCP 配置在~/.cursor/mcp.jsonmacOS/Linux或对应平台的配置目录内容如下{ mcpServers: { weather: { command: node, args: [/绝对路径/weather-mcp/server.js] } } }Claude Code 的配置类似放在~/.claude/settings.json或项目级.mcp.json里结构一致。如果你用的是 Cline 或 Roo Code它们也读同样的mcpServers字段。这里的关键是args里必须写绝对路径相对路径在不同工作目录下会找不到文件。如果你需要让 MCP Server 内部调用模型比如做 Sampling那就要在 Server 里配置 TaoToken 的 endpoint。这种情况下建议把 Key 放在环境变量里通过env字段传给 Server{ mcpServers: { weather: { command: node, args: [/绝对路径/weather-mcp/server.js], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }这样 Server 代码里用process.env.TAOTOKEN_API_KEY读取避免把 Key 硬编码进源码。三件套Base URL、Key、Model ID在这里就齐了Base URL 是https://taotoken.net/apiKey 走环境变量Model ID 在 Server 发起模型请求时填在model字段。4. 验证请求一次完整的 JSON-RPC 工具调用配置写完后不要急着在 Cursor 里点先用官方 Inspector 验证 Server 本身是否正常。安装并启动npx modelcontextprotocol/inspector node /绝对路径/weather-mcp/server.jsInspector 会打开一个网页界面左侧能看到tools/list返回的getWeather。点进去在参数框里填{city: 北京}点调用。如果右侧返回北京今天晴32℃说明 Server 的 JSON-RPC 处理完全正常。这一步验证的是 MCP Server 侧。接下来验证客户端侧。在 Cursor 里重启后打开对话窗口输入“北京天气怎么样”正常情况下 Cursor 会显示正在调用getWeather然后返回结果。如果 Cursor 没有触发工具调用先检查 MCP 配置里的路径是否正确再看 Cursor 的 MCP 面板里 Server 状态是不是绿色。如果你想看底层 JSON-RPC 到底发了什么可以在 Server 里加一行日志server.setRequestHandler(tools/call, async (req) { console.error(收到调用:, JSON.stringify(req.params)); // ... });然后在 Cursor 的 MCP 日志里就能看到完整的请求体包括jsonrpc、id、method、params四个字段。一次标准的tools/call请求长这样{ jsonrpc: 2.0, id: 2, method: tools/call, params: { name: getWeather, arguments: { city: 北京 } } }Server 的响应则是{ jsonrpc: 2.0, id: 2, result: { content: [{ type: text, text: 北京今天晴32℃ }] } }看到这个请求响应配对就说明整条链路通了。如果模型侧也要验证可以在 Cursor 里问一个需要推理的问题比如“北京和上海哪个更热”观察它是否先调用两次getWeather再比较。这一步能确认模型确实在根据工具描述做决策而不是瞎编。5. 本篇常见错排查401、local proxy failed 与 reading choices排障时按链路分段定位比盲目改配置高效得多。下面是我遇到过的高频错误和对应处理。401 Unauthorized这个几乎都是 Key 的问题。先确认 Key 没有多余空格或换行再确认请求头是Authorization: Bearer sk-xxx格式。如果你在 MCP Server 里通过环境变量传 Key检查env字段有没有写对以及 Server 代码里读取的变量名是否一致。还有一种情况是 Key 本身过期或被禁用用第 2 节的 curl 命令单独验证一次就能排除。local proxy failed这个错误通常出现在客户端连接 MCP Server 的阶段不是模型调用阶段。常见原因是command或args路径写错Node 找不到入口文件。把args里的路径换成绝对路径并确认文件确实存在。另一个原因是 Server 启动后立刻崩溃比如console.log污染了 stdout或者 import 的模块路径不对。在终端里手动执行node /绝对路径/server.js看有没有报错能快速定位。reading choices这个错误说明代码在解析模型响应时期望的choices字段不存在。原因通常是模型调用返回了错误结构比如 401 的 error 对象或者返回的是流式数据但代码按非流式解析。先确认模型请求本身成功用 curl 验证再检查 SDK 调用时stream参数是否和解析逻辑匹配。如果用的是 OpenAI 兼容 SDKBase URL 要填https://taotoken.net/api不要漏掉或写错。OAuth 相关报错部分客户端在连接远程 MCP Server 时会走 OAuth 流程如果 Server 没有实现对应的认证端点就会报 OAuth 错误。本地 stdio 模式的 Server 不涉及 OAuth如果你遇到这类错误先确认自己用的是 stdio 而不是 HTTP transport。远程部署时才需要处理认证本地开发阶段用 stdio 最省事。工具列表为空客户端连上了但看不到工具检查tools/list的返回结构。必须是{ tools: [...] }每个工具要有name、description、inputSchema三个字段。inputSchema必须是合法的 JSON Schematype为objectproperties里每个参数要有type。少一个字段都可能导致客户端解析失败静默丢弃。调用成功但模型不触发工具这通常是description写得太模糊。把“查询天气”改成“查询指定城市当前天气返回温度和天气状况”模型选择工具的准确率会明显提升。工具名用动词加名词的格式比如getWeather而不是weather。6. 语义一致 CTA把这条链路用到真实项目里最小链路跑通后下一步是把它扩展成真正的工具链。你可以按这个顺序推进先给 MCP Server 加第二个工具比如查空气质量验证多工具场景下模型的选择逻辑再把 Server 里的假数据换成真实 HTTP 调用注意加超时和错误处理最后把 Server 部署到远程用 HTTP transport 替代 stdio这时才需要处理认证和并发。模型调用这一侧如果你要长期做编码类 Agent建议用 Coding Plan它在长上下文和代码任务上的表现更稳定配置方式和普通 API 一致Base URL 同样是https://taotoken.net/api。如果只是验证模型对话效果可以直接用模型对话页面快速试。接入文档里有各客户端的详细配置示例遇到 endpoint 或模型 ID 的问题可以先查文档。Key 的管理在 API Keys 页面建议给不同项目建不同的 Key方便排查和轮换。控制台里能看到调用量和错误分布排障时比翻日志快。整条链路的核心其实就三件事MCP Server 把工具描述清楚客户端把 Server 路径配对模型侧把 Base URL、Key、Model ID 填对。这三件事各自验证通过串起来就不会有大问题。
MCP协议开发实战：从零搭建 AI Agent 工具链（2026最新版）——用 TaoToken 统一 Key 打通 JSON-RPC 调用链
1. 从一次 JSON-RPC 调用失败说起MCP 工具链到底卡在哪如果你正在做 AI Agent 工具链大概率遇到过这种场景本地 MCP Server 明明跑起来了Cursor 或 Claude Desktop 里也能看到工具列表但一到真正调用就报local proxy failed或者reading choices之类的错。更让人头疼的是你手里可能同时有 OpenAI、Claude、Gemini 三套 Key每接一个客户端就要重新配一遍 Base URL 和模型名改到最后自己都记不清哪个 Key 对应哪个 endpoint。MCPModel Context Protocol本身并不复杂底层就是 JSON-RPC 2.0一次tools/call请求发出去Server 执行完把结果塞回content数组里。真正麻烦的是“工具链”这三个字——它意味着你要把模型调用、MCP Server、客户端配置、鉴权这几段串起来任何一段的 endpoint 或 Key 写错整条链路就断。这篇内容面向的是已经写过一点 MCP Server、但还没把整条链路跑顺的开发者。我会用一个天气查询 MCP Server 作为最小案例把 JSON-RPC 的请求响应、TaoToken 统一 Key 的 endpoint 填写、以及一次完整的工具调用验证动作全部走一遍。你跟着做完应该能得到一个能被 Cursor 或 Claude Code 正常调用的 MCP 工具并且知道每一段出错时该看哪里。先说清楚 TaoToken 在这条链路里的位置它是一个兼容 OpenAI 接口规范的模型调用入口你拿一个 Key 就能访问多种模型省去为每个客户端单独申请和切换 Key 的麻烦。MCP Server 负责暴露工具TaoToken 负责提供模型推理能力两者通过客户端Cursor、Claude Code 等串起来。下面从环境准备开始。2. TaoToken 前置准备统一 Key 与 endpoint 怎么填在写 MCP Server 之前先把模型调用这一段打通否则后面调试工具调用时你分不清是 MCP 的问题还是模型鉴权的问题。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 Base URL 使用。官网入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册和查看文档都从这里进。拿到 Key 之后第一件事是确认它能正常调用模型。我用 curl 做一次最小验证这样不依赖任何 SDK能最快定位问题curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复ok}], max_tokens: 10 }如果返回里能看到choices数组和正常的content说明 Key 和 endpoint 都没问题。这里有个细节Base URL 填https://taotoken.net/api具体路径由 SDK 自己拼/v1/chat/completions不要手动把/v1写进 Base URL否则会出现双斜杠或路径重复。接下来是模型 ID 的确认。TaoToken 支持多种模型你在请求体里填的model字段要和平台文档里列出的 ID 完全一致。常见的有gpt-4o-mini、claude-3-5-sonnet这类具体以你账号下可用的为准。如果你在 Cursor 里配置模型名要填在 Cursor 的模型设置里如果在 Claude Code 里用则通过环境变量或配置文件指定。对于 MCP 工具链来说模型调用和 MCP Server 是两条独立的线。模型负责“决定调用哪个工具、生成什么参数”MCP Server 负责“执行工具、返回结果”。所以先把模型这条线用 curl 验证通过再去写 MCP Server排障时会清晰很多。我试过在没验证模型的情况下直接调 MCP结果报了一堆reading choices的错最后发现是 Key 里多了一个空格。3. 可复制配置MCP Server 与客户端 settings 片段这一节给出可以直接复制的配置。先看 MCP Server 侧。我用 Node.js 写一个最小的天气查询 Server依赖官方 SDKmkdir weather-mcp cd weather-mcp npm init -y npm install modelcontextprotocol/sdk创建server.js核心是注册tools/list和tools/call两个 handlerimport { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new Server( { name: weather-mcp, version: 1.0.0 }, { capabilities: { tools: {} } } ); server.setRequestHandler(tools/list, async () ({ tools: [{ name: getWeather, description: 查询指定城市当前天气, inputSchema: { type: object, properties: { city: { type: string, description: 城市名称 } }, required: [city] } }] })); server.setRequestHandler(tools/call, async (req) { if (req.params.name getWeather) { const city req.params.arguments.city; return { content: [{ type: text, text: ${city}今天晴32℃ }] }; } throw new Error(Unknown tool); }); const transport new StdioServerTransport(); await server.connect(transport);注意console.error可以用于日志但绝对不能用console.log因为 stdio 模式下 stdout 是 JSON-RPC 的通道混入普通文本会直接破坏协议客户端会报解析失败。然后是客户端配置。Cursor 的 MCP 配置在~/.cursor/mcp.jsonmacOS/Linux或对应平台的配置目录内容如下{ mcpServers: { weather: { command: node, args: [/绝对路径/weather-mcp/server.js] } } }Claude Code 的配置类似放在~/.claude/settings.json或项目级.mcp.json里结构一致。如果你用的是 Cline 或 Roo Code它们也读同样的mcpServers字段。这里的关键是args里必须写绝对路径相对路径在不同工作目录下会找不到文件。如果你需要让 MCP Server 内部调用模型比如做 Sampling那就要在 Server 里配置 TaoToken 的 endpoint。这种情况下建议把 Key 放在环境变量里通过env字段传给 Server{ mcpServers: { weather: { command: node, args: [/绝对路径/weather-mcp/server.js], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }这样 Server 代码里用process.env.TAOTOKEN_API_KEY读取避免把 Key 硬编码进源码。三件套Base URL、Key、Model ID在这里就齐了Base URL 是https://taotoken.net/apiKey 走环境变量Model ID 在 Server 发起模型请求时填在model字段。4. 验证请求一次完整的 JSON-RPC 工具调用配置写完后不要急着在 Cursor 里点先用官方 Inspector 验证 Server 本身是否正常。安装并启动npx modelcontextprotocol/inspector node /绝对路径/weather-mcp/server.jsInspector 会打开一个网页界面左侧能看到tools/list返回的getWeather。点进去在参数框里填{city: 北京}点调用。如果右侧返回北京今天晴32℃说明 Server 的 JSON-RPC 处理完全正常。这一步验证的是 MCP Server 侧。接下来验证客户端侧。在 Cursor 里重启后打开对话窗口输入“北京天气怎么样”正常情况下 Cursor 会显示正在调用getWeather然后返回结果。如果 Cursor 没有触发工具调用先检查 MCP 配置里的路径是否正确再看 Cursor 的 MCP 面板里 Server 状态是不是绿色。如果你想看底层 JSON-RPC 到底发了什么可以在 Server 里加一行日志server.setRequestHandler(tools/call, async (req) { console.error(收到调用:, JSON.stringify(req.params)); // ... });然后在 Cursor 的 MCP 日志里就能看到完整的请求体包括jsonrpc、id、method、params四个字段。一次标准的tools/call请求长这样{ jsonrpc: 2.0, id: 2, method: tools/call, params: { name: getWeather, arguments: { city: 北京 } } }Server 的响应则是{ jsonrpc: 2.0, id: 2, result: { content: [{ type: text, text: 北京今天晴32℃ }] } }看到这个请求响应配对就说明整条链路通了。如果模型侧也要验证可以在 Cursor 里问一个需要推理的问题比如“北京和上海哪个更热”观察它是否先调用两次getWeather再比较。这一步能确认模型确实在根据工具描述做决策而不是瞎编。5. 本篇常见错排查401、local proxy failed 与 reading choices排障时按链路分段定位比盲目改配置高效得多。下面是我遇到过的高频错误和对应处理。401 Unauthorized这个几乎都是 Key 的问题。先确认 Key 没有多余空格或换行再确认请求头是Authorization: Bearer sk-xxx格式。如果你在 MCP Server 里通过环境变量传 Key检查env字段有没有写对以及 Server 代码里读取的变量名是否一致。还有一种情况是 Key 本身过期或被禁用用第 2 节的 curl 命令单独验证一次就能排除。local proxy failed这个错误通常出现在客户端连接 MCP Server 的阶段不是模型调用阶段。常见原因是command或args路径写错Node 找不到入口文件。把args里的路径换成绝对路径并确认文件确实存在。另一个原因是 Server 启动后立刻崩溃比如console.log污染了 stdout或者 import 的模块路径不对。在终端里手动执行node /绝对路径/server.js看有没有报错能快速定位。reading choices这个错误说明代码在解析模型响应时期望的choices字段不存在。原因通常是模型调用返回了错误结构比如 401 的 error 对象或者返回的是流式数据但代码按非流式解析。先确认模型请求本身成功用 curl 验证再检查 SDK 调用时stream参数是否和解析逻辑匹配。如果用的是 OpenAI 兼容 SDKBase URL 要填https://taotoken.net/api不要漏掉或写错。OAuth 相关报错部分客户端在连接远程 MCP Server 时会走 OAuth 流程如果 Server 没有实现对应的认证端点就会报 OAuth 错误。本地 stdio 模式的 Server 不涉及 OAuth如果你遇到这类错误先确认自己用的是 stdio 而不是 HTTP transport。远程部署时才需要处理认证本地开发阶段用 stdio 最省事。工具列表为空客户端连上了但看不到工具检查tools/list的返回结构。必须是{ tools: [...] }每个工具要有name、description、inputSchema三个字段。inputSchema必须是合法的 JSON Schematype为objectproperties里每个参数要有type。少一个字段都可能导致客户端解析失败静默丢弃。调用成功但模型不触发工具这通常是description写得太模糊。把“查询天气”改成“查询指定城市当前天气返回温度和天气状况”模型选择工具的准确率会明显提升。工具名用动词加名词的格式比如getWeather而不是weather。6. 语义一致 CTA把这条链路用到真实项目里最小链路跑通后下一步是把它扩展成真正的工具链。你可以按这个顺序推进先给 MCP Server 加第二个工具比如查空气质量验证多工具场景下模型的选择逻辑再把 Server 里的假数据换成真实 HTTP 调用注意加超时和错误处理最后把 Server 部署到远程用 HTTP transport 替代 stdio这时才需要处理认证和并发。模型调用这一侧如果你要长期做编码类 Agent建议用 Coding Plan它在长上下文和代码任务上的表现更稳定配置方式和普通 API 一致Base URL 同样是https://taotoken.net/api。如果只是验证模型对话效果可以直接用模型对话页面快速试。接入文档里有各客户端的详细配置示例遇到 endpoint 或模型 ID 的问题可以先查文档。Key 的管理在 API Keys 页面建议给不同项目建不同的 Key方便排查和轮换。控制台里能看到调用量和错误分布排障时比翻日志快。整条链路的核心其实就三件事MCP Server 把工具描述清楚客户端把 Server 路径配对模型侧把 Base URL、Key、Model ID 填对。这三件事各自验证通过串起来就不会有大问题。