1. 从 stdio 到 JSON-RPCMCP 在 Agent 里到底怎么跑起来MCPModel Context Protocol是一套让 Agent 与外部工具解耦的开放协议它把「工具定义」和「工具执行」从智能体进程里拆出来变成独立的 Server 端点。它适合谁适合那些已经写过 Function Calling、但被「工具硬编码在业务代码里、换个宿主就得重写一遍」折磨过的开发者。我这次要做的是一个最小可跑的本地 MCP Server用 stdio 传输层承载 JSON-RPC 消息暴露一个createRefund工具再让 Agent 侧通过 TaoToken 统一 Key 把模型调用接上最后完整验证一次工具调用链路。很多人第一次接触 MCP 会误以为它是「Function Calling 的替代品」其实两者根本不在同一层。Function Calling 是模型能力——你在请求里塞tools字段模型回你一个tool_callsMCP 是工程协议——它规定工具怎么被描述、怎么被调用、怎么把结果拿回来。模型侧看到的 schema 一模一样变的只是「工具从哪来、在哪执行」。理解这一点后面所有配置和排障才有主线。这篇笔记按可跟做的顺序走先讲清楚 stdio 和 JSON-RPC 的分工再给出可复制的 server 配置片段然后跑一次完整的tools/listtools/call验证最后把常见报错逐个对照排查。模型侧统一走 TaoToken 的 API 通道Key 和 Base URL 只配一次Agent 和 MCP Server 都能复用。1.1 stdio 传输层进程边界就是信任边界stdio 是 MCP 最朴素的传输方式Host 用ProcessBuilder拉起一个子进程双方通过 stdin/stdout 交换 JSON-RPC 报文stderr 专门留给日志。它的精妙之处在于——进程边界天然就是信任边界。你不需要服务发现、不需要端口分配、不需要鉴权、不需要 TLS因为「我自己 fork 的子进程」本身就是权限来源。这里有一条硬约定也是新手最容易踩的坑stdout 只能写协议数据日志必须走 stderr。你在 server 里随手写一个console.log就等于往协议通道里插了一段非法 JSON客户端解析直接挂掉。我试过在调试时忘了这茬连接莫名其妙断开查了半小时才发现是日志打错了流。stdio 的代价是它必然只能本地。协议定义它就是 client-launched subprocess跨机器物理上不可能。所以本地工具、IDE 插件、开发调试用 stdio团队共享、生产部署换 HTTP transport。这个选型后面还会展开。1.2 JSON-RPC 消息格式四条消息就是全部交互MCP 的数据层基于 JSON-RPC 2.0stdio 下就是按行分隔的 JSON 文本在管道里来回。一次完整的工具调用核心就四条消息阶段消息方向作用握手initializeClient → Server协商版本、交换能力声明握手notifications/initializedClient → Server通知无 id、不回应说明书tools/listClient → Server拿 name description inputSchema执行tools/callClient → Server传参数拿 content[] 回来工具定义本身就是一份 JSON Schema。比如createRefund的inputSchema里itemName和reason都是 string 且 required。这份结构和 Function Calling 里tools字段的结构是同一类东西——模型看到的还是这份 schema所以 Tool 设计原则三段式描述、参数不超 3-4 个、不让模型猜 ID在 MCP 下一条都不变。1.3 Function Calling 与 MCP 的分工把两者的对应关系记住MCP 的交互就不会忘Function Calling 侧MCP 侧请求里的tools字段tools/list的返回值模型返回的tool_calls触发tools/call的入参回写给模型的tool消息tools/call返回的content[]所以一轮对话的模型请求次数不变仍是 N1 次。MCP 不增加模型调用只增加 Agent 侧的 IPC 往返token 成本也完全不变因为 schema 逐字节相同。MCP 取代的不是 Function Calling 这个机制而是「工具硬编码在智能体里」这种工程组织方式。2. TaoToken 前置统一 Key 与 API 通道在动手写 server 之前先把模型侧的通道准备好。MCP 本身不碰模型但 Agent 要调模型来决策「调哪个工具」这一步走 TaoToken 的 API 通道最省事——一个 Key、一个 Base URLAgent 和后续的验证脚本都能复用。TaoToken 在这里扮演的是「模型侧统一入口」你不需要为每个模型单独维护一套鉴权和地址把 Base URL 指向https://taotoken.net/apiKey 用同一个模型 ID 按需切换即可。对 MCP 场景来说这意味着 Agent 侧的工具 schema 发给哪个模型、用哪个 Key都是配置项而不是代码改动。2.1 拿到 Key 与确认 Base URL登录后在控制台创建 API Key复制出来先存到环境变量里别硬编码进代码export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiBase URL 用https://taotoken.net/api不要带任何多余路径。模型 ID 按你实际要用的填比如claude-sonnet-4-20250514或gpt-4o具体以控制台模型列表为准。2.2 为什么 MCP 场景要统一 KeyMCP 的链路是「Host → Client → Server → 执行」模型调用发生在 Host 侧。如果你有多个 Agent、多个 MCP Server每个都配一套 Key 会很快失控。统一走 TaoToken 之后Key 轮换只改一处模型切换只改一个 Model ID排障时也能确定「模型侧没问题」再往协议层查。注意Key 只放在环境变量或密钥管理里不要写进settings.json、auth.json这类会进版本库的文件。MCP Server 的配置里如果需要引用用环境变量占位。2.3 模型侧与协议侧的边界再强调一次边界TaoToken 管的是「模型怎么被调用」MCP 管的是「工具怎么被描述和执行」。两者通过 Agent 的 Function Calling 逻辑衔接——Agent 从 MCP Server 拿到tools/list转成模型请求里的tools字段模型返回tool_callsAgent 再转成tools/call发给 Server。这条链路里TaoToken 只在「发模型请求」这一步出现。3. 可复制配置MCP Server 与客户端接入这一节给出可直接复制的配置片段。分两部分MCP Server 的启动配置以及客户端Host如何声明这个 server。路径和字段名保持和实际一致你改的时候只改路径和命令。3.1 MCP Server 的 stdio 启动配置假设你的 server 入口是mcp-server/dist/index.js用 Node 启动。客户端侧的配置通常长这样以通用 MCP 客户端配置为例{ mcpServers: { refund-server: { command: node, args: [mcp-server/dist/index.js], env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }三个关键字段command是可执行程序args是参数数组env是注入给子进程的环境变量。env里用${VAR}占位避免把 Key 写死。3.2 Server 端工具注册片段Server 端注册工具时name、description、inputSchema三件套缺一不可。description是模型选工具的全部依据要写清楚「什么时候该调、什么时候不该调」server.setRequestHandler(ListToolsRequestSchema, async () ({ tools: [{ name: createRefund, description: 为用户发起退款申请。仅在用户已确认商品存在严重质量问题时调用调用后款项按原路径退回, inputSchema: { type: object, properties: { itemName: { type: string, description: 商品名称或描述用户没说清楚时填未知商品 }, reason: { type: string, description: 质量问题的具体描述例如袖口开线 } }, required: [itemName, reason] } }] }));3.3 客户端接入的三件套无论你用哪种客户端接入一个 MCP Server 都要写全三件套Base URL Key Model ID。Base URL 指向https://taotoken.net/apiKey 用TAOTOKEN_API_KEYModel ID 按控制台填。这三项在 Agent 侧配置一次MCP Server 侧只负责工具逻辑不碰模型鉴权。如果你用的是 Claude Code 这类工具配置通常落在settings.json如果是 Codex 系可能在auth.json。不管文件名是什么字段语义一致地址、密钥、模型。三件套写全缺一个就会在请求阶段报鉴权或模型不存在。4. 验证请求跑通一次完整的工具调用配置写完必须验证。验证分两步先确认 server 本身能正确响应tools/list再确认tools/call能真正执行并返回结果。4.1 手动调协议验证 server最快的方式是脱离框架直接用管道喂 JSON 给 serverprintf %s\n \ {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:probe,version:0.1.0}}} \ {jsonrpc:2.0,method:notifications/initialized} \ {jsonrpc:2.0,id:2,method:tools/list,params:{}} \ | node mcp-server/dist/index.js预期看到initialize的响应里带serverInfo和capabilitiestools/list的响应里带tools数组。如果这一步就失败问题在 server 本身不用往客户端查。4.2 验证 tools/call确认tools/list正常后再发一次调用printf %s\n \ {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:probe,version:0.1.0}}} \ {jsonrpc:2.0,method:notifications/initialized} \ {jsonrpc:2.0,id:3,method:tools/call,params:{name:createRefund,arguments:{itemName:连衣裙,reason:袖口开线}}} \ | node mcp-server/dist/index.js预期返回content数组里面是type: text的结果文本。同时 stderr 里应该能看到 server 打的执行日志——注意是 stderr不是 stdout。4.3 端到端验证server 单独验证通过后再走 Agent 端到端。Agent 侧会先发tools/list拿 schema转成模型请求的tools字段模型返回tool_callsAgent 再发tools/call。整条链路跑通后你会在日志里看到模型请求 → tool_calls → tools/call → content → 第二次模型请求 → 最终话术。5. 常见报错排查401、local proxy failed、reading choices这一节对照真实报错逐个排查。MCP 链路的报错可能出现在三个位置模型侧、协议层、server 侧定位顺序是先模型后协议再 server。5.1 401 Unauthorized模型请求返回 401说明 Key 或 Base URL 有问题。检查三件套Base URL 是不是https://taotoken.net/apiKey 是不是环境变量里那个Model ID 是不是控制台里存在的。常见错误是把 Base URL 写成了带路径的地址或者 Key 复制时带了空格。5.2 local proxy failed这个报错通常出现在客户端尝试连接 MCP Server 时。检查command和args路径是否正确node是否在 PATH 里dist/index.js是否真的存在。如果 server 启动就崩客户端会报连接失败。先用 4.1 的手动管道验证 server 能独立跑起来。5.3 reading choices 相关报错这类报错一般出现在解析模型响应时说明响应结构不符合预期。可能是模型返回了非标准格式或者请求里的tools字段格式不对。检查 Agent 侧把tools/list的 schema 转成模型请求时字段名和结构是否和模型 API 要求一致。5.4 OAuth 相关报错如果客户端报 OAuth 错误说明它尝试走 OAuth 流程而不是 API Key。检查配置里是不是误填了 OAuth 相关字段或者客户端默认走了 OAuth 模式。MCP 场景下模型侧用 API Key 即可不需要 OAuth。5.5 工具静默消失最隐蔽的一类问题server 挂了但客户端只打了一条 warn工具无声消失模型变成「只说不做」。表现和「提示词没写要调用工具」一模一样但根因完全不同。解决办法是显式设置failIfOneServerFails(true)宁可启动失败不要静默降级。6. 接入文档与后续步骤排障和接入相关的细节建议对照官方文档逐项核对。API Key 在控制台创建接入文档里有完整的字段说明和示例。模型侧的验证可以用模型对话页面直接试确认 Key 和 Model ID 没问题再往 Agent 里接。如果你要长期跑编码类 AgentCoding Plan 更适合持续调用场景。API Key 创建https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc模型对话验证https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchatCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan最后留一个判断标准这个工具需要被第二个宿主消费吗需要就用 MCP不需要就用进程内的 Function Calling。单进程内用 MCP 替代本地工具是它最没有价值的用法——你付出了额外的进程、协议、故障模式换回来的收益是零因为收益全在「跨宿主」这个维度上。
1. 从 stdio 到 JSON-RPCMCP 在 Agent 里到底怎么跑起来MCPModel Context Protocol是一套让 Agent 与外部工具解耦的开放协议它把「工具定义」和「工具执行」从智能体进程里拆出来变成独立的 Server 端点。它适合谁适合那些已经写过 Function Calling、但被「工具硬编码在业务代码里、换个宿主就得重写一遍」折磨过的开发者。我这次要做的是一个最小可跑的本地 MCP Server用 stdio 传输层承载 JSON-RPC 消息暴露一个createRefund工具再让 Agent 侧通过 TaoToken 统一 Key 把模型调用接上最后完整验证一次工具调用链路。很多人第一次接触 MCP 会误以为它是「Function Calling 的替代品」其实两者根本不在同一层。Function Calling 是模型能力——你在请求里塞tools字段模型回你一个tool_callsMCP 是工程协议——它规定工具怎么被描述、怎么被调用、怎么把结果拿回来。模型侧看到的 schema 一模一样变的只是「工具从哪来、在哪执行」。理解这一点后面所有配置和排障才有主线。这篇笔记按可跟做的顺序走先讲清楚 stdio 和 JSON-RPC 的分工再给出可复制的 server 配置片段然后跑一次完整的tools/listtools/call验证最后把常见报错逐个对照排查。模型侧统一走 TaoToken 的 API 通道Key 和 Base URL 只配一次Agent 和 MCP Server 都能复用。1.1 stdio 传输层进程边界就是信任边界stdio 是 MCP 最朴素的传输方式Host 用ProcessBuilder拉起一个子进程双方通过 stdin/stdout 交换 JSON-RPC 报文stderr 专门留给日志。它的精妙之处在于——进程边界天然就是信任边界。你不需要服务发现、不需要端口分配、不需要鉴权、不需要 TLS因为「我自己 fork 的子进程」本身就是权限来源。这里有一条硬约定也是新手最容易踩的坑stdout 只能写协议数据日志必须走 stderr。你在 server 里随手写一个console.log就等于往协议通道里插了一段非法 JSON客户端解析直接挂掉。我试过在调试时忘了这茬连接莫名其妙断开查了半小时才发现是日志打错了流。stdio 的代价是它必然只能本地。协议定义它就是 client-launched subprocess跨机器物理上不可能。所以本地工具、IDE 插件、开发调试用 stdio团队共享、生产部署换 HTTP transport。这个选型后面还会展开。1.2 JSON-RPC 消息格式四条消息就是全部交互MCP 的数据层基于 JSON-RPC 2.0stdio 下就是按行分隔的 JSON 文本在管道里来回。一次完整的工具调用核心就四条消息阶段消息方向作用握手initializeClient → Server协商版本、交换能力声明握手notifications/initializedClient → Server通知无 id、不回应说明书tools/listClient → Server拿 name description inputSchema执行tools/callClient → Server传参数拿 content[] 回来工具定义本身就是一份 JSON Schema。比如createRefund的inputSchema里itemName和reason都是 string 且 required。这份结构和 Function Calling 里tools字段的结构是同一类东西——模型看到的还是这份 schema所以 Tool 设计原则三段式描述、参数不超 3-4 个、不让模型猜 ID在 MCP 下一条都不变。1.3 Function Calling 与 MCP 的分工把两者的对应关系记住MCP 的交互就不会忘Function Calling 侧MCP 侧请求里的tools字段tools/list的返回值模型返回的tool_calls触发tools/call的入参回写给模型的tool消息tools/call返回的content[]所以一轮对话的模型请求次数不变仍是 N1 次。MCP 不增加模型调用只增加 Agent 侧的 IPC 往返token 成本也完全不变因为 schema 逐字节相同。MCP 取代的不是 Function Calling 这个机制而是「工具硬编码在智能体里」这种工程组织方式。2. TaoToken 前置统一 Key 与 API 通道在动手写 server 之前先把模型侧的通道准备好。MCP 本身不碰模型但 Agent 要调模型来决策「调哪个工具」这一步走 TaoToken 的 API 通道最省事——一个 Key、一个 Base URLAgent 和后续的验证脚本都能复用。TaoToken 在这里扮演的是「模型侧统一入口」你不需要为每个模型单独维护一套鉴权和地址把 Base URL 指向https://taotoken.net/apiKey 用同一个模型 ID 按需切换即可。对 MCP 场景来说这意味着 Agent 侧的工具 schema 发给哪个模型、用哪个 Key都是配置项而不是代码改动。2.1 拿到 Key 与确认 Base URL登录后在控制台创建 API Key复制出来先存到环境变量里别硬编码进代码export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiBase URL 用https://taotoken.net/api不要带任何多余路径。模型 ID 按你实际要用的填比如claude-sonnet-4-20250514或gpt-4o具体以控制台模型列表为准。2.2 为什么 MCP 场景要统一 KeyMCP 的链路是「Host → Client → Server → 执行」模型调用发生在 Host 侧。如果你有多个 Agent、多个 MCP Server每个都配一套 Key 会很快失控。统一走 TaoToken 之后Key 轮换只改一处模型切换只改一个 Model ID排障时也能确定「模型侧没问题」再往协议层查。注意Key 只放在环境变量或密钥管理里不要写进settings.json、auth.json这类会进版本库的文件。MCP Server 的配置里如果需要引用用环境变量占位。2.3 模型侧与协议侧的边界再强调一次边界TaoToken 管的是「模型怎么被调用」MCP 管的是「工具怎么被描述和执行」。两者通过 Agent 的 Function Calling 逻辑衔接——Agent 从 MCP Server 拿到tools/list转成模型请求里的tools字段模型返回tool_callsAgent 再转成tools/call发给 Server。这条链路里TaoToken 只在「发模型请求」这一步出现。3. 可复制配置MCP Server 与客户端接入这一节给出可直接复制的配置片段。分两部分MCP Server 的启动配置以及客户端Host如何声明这个 server。路径和字段名保持和实际一致你改的时候只改路径和命令。3.1 MCP Server 的 stdio 启动配置假设你的 server 入口是mcp-server/dist/index.js用 Node 启动。客户端侧的配置通常长这样以通用 MCP 客户端配置为例{ mcpServers: { refund-server: { command: node, args: [mcp-server/dist/index.js], env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY}, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }三个关键字段command是可执行程序args是参数数组env是注入给子进程的环境变量。env里用${VAR}占位避免把 Key 写死。3.2 Server 端工具注册片段Server 端注册工具时name、description、inputSchema三件套缺一不可。description是模型选工具的全部依据要写清楚「什么时候该调、什么时候不该调」server.setRequestHandler(ListToolsRequestSchema, async () ({ tools: [{ name: createRefund, description: 为用户发起退款申请。仅在用户已确认商品存在严重质量问题时调用调用后款项按原路径退回, inputSchema: { type: object, properties: { itemName: { type: string, description: 商品名称或描述用户没说清楚时填未知商品 }, reason: { type: string, description: 质量问题的具体描述例如袖口开线 } }, required: [itemName, reason] } }] }));3.3 客户端接入的三件套无论你用哪种客户端接入一个 MCP Server 都要写全三件套Base URL Key Model ID。Base URL 指向https://taotoken.net/apiKey 用TAOTOKEN_API_KEYModel ID 按控制台填。这三项在 Agent 侧配置一次MCP Server 侧只负责工具逻辑不碰模型鉴权。如果你用的是 Claude Code 这类工具配置通常落在settings.json如果是 Codex 系可能在auth.json。不管文件名是什么字段语义一致地址、密钥、模型。三件套写全缺一个就会在请求阶段报鉴权或模型不存在。4. 验证请求跑通一次完整的工具调用配置写完必须验证。验证分两步先确认 server 本身能正确响应tools/list再确认tools/call能真正执行并返回结果。4.1 手动调协议验证 server最快的方式是脱离框架直接用管道喂 JSON 给 serverprintf %s\n \ {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:probe,version:0.1.0}}} \ {jsonrpc:2.0,method:notifications/initialized} \ {jsonrpc:2.0,id:2,method:tools/list,params:{}} \ | node mcp-server/dist/index.js预期看到initialize的响应里带serverInfo和capabilitiestools/list的响应里带tools数组。如果这一步就失败问题在 server 本身不用往客户端查。4.2 验证 tools/call确认tools/list正常后再发一次调用printf %s\n \ {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:probe,version:0.1.0}}} \ {jsonrpc:2.0,method:notifications/initialized} \ {jsonrpc:2.0,id:3,method:tools/call,params:{name:createRefund,arguments:{itemName:连衣裙,reason:袖口开线}}} \ | node mcp-server/dist/index.js预期返回content数组里面是type: text的结果文本。同时 stderr 里应该能看到 server 打的执行日志——注意是 stderr不是 stdout。4.3 端到端验证server 单独验证通过后再走 Agent 端到端。Agent 侧会先发tools/list拿 schema转成模型请求的tools字段模型返回tool_callsAgent 再发tools/call。整条链路跑通后你会在日志里看到模型请求 → tool_calls → tools/call → content → 第二次模型请求 → 最终话术。5. 常见报错排查401、local proxy failed、reading choices这一节对照真实报错逐个排查。MCP 链路的报错可能出现在三个位置模型侧、协议层、server 侧定位顺序是先模型后协议再 server。5.1 401 Unauthorized模型请求返回 401说明 Key 或 Base URL 有问题。检查三件套Base URL 是不是https://taotoken.net/apiKey 是不是环境变量里那个Model ID 是不是控制台里存在的。常见错误是把 Base URL 写成了带路径的地址或者 Key 复制时带了空格。5.2 local proxy failed这个报错通常出现在客户端尝试连接 MCP Server 时。检查command和args路径是否正确node是否在 PATH 里dist/index.js是否真的存在。如果 server 启动就崩客户端会报连接失败。先用 4.1 的手动管道验证 server 能独立跑起来。5.3 reading choices 相关报错这类报错一般出现在解析模型响应时说明响应结构不符合预期。可能是模型返回了非标准格式或者请求里的tools字段格式不对。检查 Agent 侧把tools/list的 schema 转成模型请求时字段名和结构是否和模型 API 要求一致。5.4 OAuth 相关报错如果客户端报 OAuth 错误说明它尝试走 OAuth 流程而不是 API Key。检查配置里是不是误填了 OAuth 相关字段或者客户端默认走了 OAuth 模式。MCP 场景下模型侧用 API Key 即可不需要 OAuth。5.5 工具静默消失最隐蔽的一类问题server 挂了但客户端只打了一条 warn工具无声消失模型变成「只说不做」。表现和「提示词没写要调用工具」一模一样但根因完全不同。解决办法是显式设置failIfOneServerFails(true)宁可启动失败不要静默降级。6. 接入文档与后续步骤排障和接入相关的细节建议对照官方文档逐项核对。API Key 在控制台创建接入文档里有完整的字段说明和示例。模型侧的验证可以用模型对话页面直接试确认 Key 和 Model ID 没问题再往 Agent 里接。如果你要长期跑编码类 AgentCoding Plan 更适合持续调用场景。API Key 创建https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc模型对话验证https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchatCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan最后留一个判断标准这个工具需要被第二个宿主消费吗需要就用 MCP不需要就用进程内的 Function Calling。单进程内用 MCP 替代本地工具是它最没有价值的用法——你付出了额外的进程、协议、故障模式换回来的收益是零因为收益全在「跨宿主」这个维度上。
