MCP 协议怎么理解？这次用 TaoToken 让 Codex 讲通 JSON-RPC 示例

读 MCP 的文章最痛苦的不是不知道协议是什么意思而是看到initialize、tools/list、tools/call就开始走神。“MCP 大白话理解”那篇的餐厅比喻很棒但比喻和真实报文之间的缝隙还得有人点破。这篇我让 Codex 来当讲解 AgentCodex 的模型通道先用 TaoToken——到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建 Key填进配置文件后再让它逐条讲。拿到 Key 后Codex 就能在一个长会话里把 Client/Server 的关系、字段含义都讲通以后你再看 MCP 日志也可以把日志贴给它继续问。1. 在 Codex 里先接好 TaoToken再谈 MCP 字段1.1 准备一把 Key不是去配 MCP很多读者看到“配置 MCP”就以为要写 JSON-RPC 服务端其实那是另一条路。本文要做的只是让 Codex 能稳定地用上模型来解释协议MCP 的事情交给 Codex 的对话能力去讲。所以准备工作只有两步打开 TaoToken注册并把 API Key 创建出来Key 先复制到剪贴板后面叫YOUR_API_KEY。确认你本机已经装好 Codex CLI。如果没有按 Codex 官方文档装完再回来看这篇。TaoToken 在这里只充当 Codex 接入模型的 API 通道不参与 MCP 协议的任何实现。协议内容是模型自己知道的通道只负责把“Codex 说的话”送到模型那里再把模型的话原样带回来。这样就把“配置一个可用模型”和“理解 MCP”两件事拆开了。1.2 编辑 ~/.codex/config.tomlCodex CLI 读的是用户目录下的config.toml不要把它和 MCP 的配置文件弄混。用文本编辑器打开~/.codex/config.toml写入下面这一段# 模型 ID 以 TaoToken 模型广场展示为准不要照抄这里的占位符 model YOUR_MODEL_ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY保存后在终端里带着 Key 启动 Codexexport TAOTOKEN_API_KEYYOUR_API_KEY codex注意几个容易踩的地方base_url写的是https://taotoken.net/api末尾不要加/v1Codex 自己会按兼容格式拼路径。model YOUR_MODEL_ID里的模型 ID 不是随便填的以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 模型广场当时列表为准。手打一个不存在的 IDCodex 会在调用时报模型相关错误。If 你之前给 Codex 配置过别的 providermodel_provider taotoken要和你[model_providers.taotoken]里的键名完全一致不能写taotoken却把 provider 段落命名为别的。配好之后先不要急着问 MCP。随便问 Codex 一句“你好”确认它走通了。如果它回答得正常说明 TaoToken 通道已经通了下面就可以开始让它讲解 MCP 报文。2. 原文的 9 行 JSON-RPC 报文对应哪三类动作2.1 餐厅比喻里的“点单—呼叫—交付”三步“MCP 大白话理解”那篇把 Client 比作天才厨师把 MCP Server 比作后厨团队这个比喻非常适合用来定位协议动作。厨师脑子里有菜谱但没有手去切鱼、没有腿去市场。他要完成一道菜必须先和后厨确认“今天有哪些人在岗”然后喊“采购员去市场买这条鱼”采购员做完再把鱼放在传递台上。这三个步骤在 MCP 协议里就是三类 methodinitializeClient 和 Server 互相确认身份、协议版本、能力清单。相当于厨师先和后厨领班碰个头说“我是新来的主厨今天按这套暗号配合”。tools/listClient 问 Server“你这里有哪些工具分别接受什么参数”。相当于厨师问采购员“你手上有什么渠道”采购员报出一串可以调用的清单。tools/callClient 指定工具名并给出实参让 Server 执行。相当于厨师对着采购员喊“调用 get_fresh_fish参数是蓝鳍金枪鱼、要今天的”。如果 Server 执行成功回包里有result如果失败回包里换成error。这两个字段不会同时出现这是 JSON-RPC 2.0 的规矩。2.2 Client 与 Server 的四组消息模板为了不让 Codex 空口讲理论我先把“原文那 9 行模板”压缩成一组最小的 MCP 会话日志存成mcp_min.json。你可以直接把下面这段贴给 Codex[ { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2025-03-26, capabilities: { tools: { listChanged: true } }, clientInfo: { name: codex, version: 0.1.0 } } }, { jsonrpc: 2.0, id: 1, result: { protocolVersion: 2025-03-26, capabilities: { tools: { listChanged: true } }, serverInfo: { name: demo-mcp-server, version: 1.0.0 } } }, { jsonrpc: 2.0, id: 2, method: tools/list, params: {} }, { jsonrpc: 2.0, id: 2, result: { tools: [ { name: search_kb, description: 在知识库中搜索文档, inputSchema: { type: object, properties: { query: { type: string }, top_k: { type: number, default: 3 } }, required: [query] } } ] } }, { jsonrpc: 2.0, id: 3, method: tools/call, params: { name: search_kb, arguments: { query: 道路阻断准确率, top_k: 5 } } }, { jsonrpc: 2.0, id: 3, result: { content: [ { type: text, text: 根据知识库道路阻断预警准确率需不低于 90% } ] } }, { jsonrpc: 2.0, id: 4, error: { code: -32601, message: Method foo/bar not found } } ]这 7 条消息已经覆盖了原文的核心结构第 1 条是握手请求第 2 条是握手成功回包第 3 条是列工具第 4 条是工具清单第 5 条是调用工具第 6 条是成功结果第 7 条是错误回包。它比原文少了 ping但足够讲清楚“握手—列工具—调用—回结果”的完整链路。3. 把 MCP 报文丢给 Codex让它逐条拆字段3.1 给 Codex 发的讲解指令现在你已经打开了 Codex模型通道是 TaoToken。下面这段指令可以直接复制进 Codex 对话框让它按“餐厅比喻 JSON-RPC 字段 报错场景”三层来拆请扮演一个只会讲大白话的 MCP 讲师。我要发给你一段 JSON-RPC 2.0 的 MCP 会话日志。 请按这个顺序讲 1. 哪几行属于 initialize 握手哪几行属于 tools/list哪几行属于 tools/call。 2. 为什么响应里的 id 必须和请求里的 id 一样。 3. result 和 error 分别在什么情况下出现为什么不会同时出现。 4. 把第 5 条那个工具的 inputSchema 翻译成一句人话。 5. 最后用餐厅比喻把整段日志重新讲一遍。 日志如下 mcp_min.json 里的内容Codex 会先标出全是method的行是请求标出带result或error的行是响应然后指出第 5 行的params.name对应第 4 行tools数组里的name。这些它都能讲得比大部分文章更细致因为它是对着真实报文逐字讲的。如果 Codex 只讲了一个大概你可以继续追一句“把第 3 条的params: {}为什么是空对象也讲一下”。空对象表示“列出全部工具不需要额外条件”所以params字段保留但内容为空。这种小细节在文章里常被跳过但模型通常能补出来。3.2 让它专门解释 result 与 error 的对应关系result和error是同一层级的两个互斥字段。Codex 会告诉你JSON-RPC 的响应里要么有result表示成功要么有error表示失败。成功时你可以拿到tools列表或content文本失败时你只能拿到code和message。你可以让 Codex 对第 7 条做一次“病历式分析”-32601是 JSON-RPC 标准错误码含义是 Method not found也就是 Client 调了一个 Server 没登记过的方法。这个场景在真实 MCP 日志里非常常见比如 Server 版本太老还没有实现resources/list而 Client 却发了一条过去Server 就会回-32601。再追问一句“如果 tools/call 执行到一半数据库挂了应该返回什么”Codex 一般会回答协议层返回result还是error取决于 Server 是否把“调用失败”当作异常来报。如果 Server 捕获了异常它会回error.code为-32603Internal error或自定义错误码如果 Server 没有捕获异常可能连接直接断开连error都没有。这里你就可以接着让它比较“返回 error 和 断开连接”对 Client 的影响这也是 MCP 排障时很难从文档里学到的部分。4. 让 Codex 反查一段陌生 MCP 日志验证是否真的听懂了4.1 从日志里认出握手与工具调用验证环节比“它讲得好不好”更实用。随便找一段你没见过的 MCP 日志把里面的 JSON 行抽出来贴给 Codex问一句这是我刚抓的一段日志。请告诉我 1. 这条日志里有没有握手成功的标志。 2. Client 一共申请调用了几次工具调了哪些工具。 3. 有没有出现 error如果有是哪个环节出的错。如果 Codex 能在几秒内指出“第一个initialize的响应里没有error所以握手成功”“后面有三次tools/call分别是 search_kb、get_weather、send_mail”这说明它已经把协议结构内化了。以后你再看到陌生日志不用自己翻字段直接复制粘贴给它省掉大部分对表时间。这一步会反复用到同一个长会话。有一个稳定模型的通道很占便宜Codex 不需要每次启动都重新理解“我们要讨论的是 MCP 协议”因为对话历史还在。即使换一个模型 ID只要还在同一个 Codex 会话里之前的上下文也保留着。4.2 手写一个 tools/call 请求做小测验如果你身边没有现成日志也可以让 Codex 出一道题。向它要一个“故意写错的 tools/call 请求”让它自己判错请你故意把一个 tools/call 请求写错例如把工具名字写成 tools 列表里不存在的值然后让我猜 Server 会返回什么。我猜完之后你再解释。我实际试下来Codex 会构造一个类似tools/call里name: search_kbs多了一个 s的场景然后补充说明Server 的tools/list只注册了search_kb所以会回-32602或-32601。如果你只改错参数类型、不改工具名则更可能得到-32602Invalid params。这种互动比单方面读文章更能暴露自己是否理解“方法名和参数是两个独立校验环节”。这个验证步骤本身不需要 TaoToken 做任何额外事情Key 仍然只在 Codex 调用模型时起作用。MCP 协议的报文在 Codex 和你的对话框之间来回答TaoToken 是那根透明的管子不碰内容。5. 配置后可能遇到的三个报错5.1 401 UnauthorizedCodex 报 401 时优先检查环境变量是不是真的被读到了。echo $TAOTOKEN_API_KEY如果输出为空说明export那一步没生效或者你打开了一个新的终端窗口之前的导出已经丢失。另外Key 必须在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的 API Key 页面创建不是网站登录密码也不是会话 token。复制时注意别把前后空格带进去。5.2 404 或模型不存在Codex 报 404 多半不是 Key 的问题而是config.toml里的model YOUR_MODEL_ID还没换成真实模型 ID。手写 ID 很容易错正确做法是去 TaoToken 模型广场找到当前可用的模型 ID原样复制到config.toml。还有一类 404 是你没有重启 Codex 进程。TOML 文件只在 Codex 启动时读取改完文件后需要退出当前会话重新codex不要想着在对话里让它“重新加载配置”CLI 工具一般没有热更新。5.3 Base URL 末尾带 /v1 导致请求路径重复有些读者用惯了 OpenAI 直连习惯性地把 Base URL 写成https://taotoken.net/api/v1。TaoToken 的接入地址就是https://taotoken.net/api末尾不要再加/v1。Codex 兼容 OpenAI 的路径习惯会在/api后面自动拼上对应路径如果你自己再加一个/v1最终请求会变成/api/v1/xxx大概率得到 404 或路由错误。如果你改完base_url还是报路径类错误可以用一条最简单的 curl 验证通道是否正常curl --location https://taotoken.net/api/models \ --header Authorization: Bearer YOUR_API_KEY这条请求只用于确认 API 通道通不通和 MCP 没有关系。能返回模型列表就说明 TaoToken 通道本身正常问题一定出在 Codex 的配置文件。6. 跑通之后去控制台对一下这次调用Codex 把 MCP 报文讲完你手里已经有了一份完整的字段速查结论。此时回到浏览器打开 TaoToken 模型对话用同一把YOUR_API_KEY发一条测试消息确认 Key 的状态和 Base URL 都没填错。如果你打算长期用 Codex 写代码、刷 MCP 日志可以再看看 Coding Plan 的套餐是否够用。新 Key 的统一创建入口在 控制台 API Keys以后 Key 快到期或者想换模型都回到那里不要直接在config.toml里乱改模型 ID。等 Codex 这边玩熟了再去看 Claude Code 的接入方式环境变量的写法和 Codex 不一样但 Base URL 用的是同一个 接入文档。把这一套链路配齐之后MCP 也好、Agent 也好都只是模型对话的一个具体场景你只需关注报文本身而不用再为“模型通道又断了”分心。