1. MCP 三件套在 Codex 里到底卡在哪Host、Client、Server 的边界MCP 协议把 AI 与外部资源的交互拆成 Host、Client、Server 三件套JSON-RPC 2.0 一上概念很清楚真要把一个 MCP 服务器在 Codex 里跑起来很多人会卡在配置文件和工具调用链条上。先把模型通道理顺打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_mcp 注册并创建 API Key让 Codex 的模型请求走 TaoToken 统一返回再回头补 MCP 服务器配置整个链路会轻很多。MCP 本身不复杂复杂的是 Host 和 Client、Server 之间的职责边界以及每一步到底该改哪个文件。1.1 原文里的 Host、Client、Server换成 Codex 会话是什么原始文章把 MCP 主机定义为 Claude Desktop 或 IDE那是 Host 的典型形态MCP 客户端负责一对一连接服务器MCP 服务器则把本地文件系统、远程 API、数据库等能力暴露成标准化工具。放到 Codex 里Host 可以理解为 Codex CLI 这个交互入口Client 是 Codex 内部负责发 JSON-RPC 请求的协议层Server 就是你用 Node、Python 或 Go 写出来的那个轻量程序。很多人在第一步就混了以为 Codex 会直接“变成” MCP 服务器。不是。Codex 是宿主和客户端它需要按配置去启动一个 MCP 服务器然后通过initialize、tools/list、tools/call这类 JSON-RPC 消息跟服务器对话。你要改的是 Codex 的~/.codex/config.toml再单独准备一个可执行的 server 文件。把这两个东西分清楚后面排错才不会乱。1.2 配置复杂性的来源不是协议难是链路长MCP 的通信流程基于 JSON-RPC 2.0支持能力协商和双向交互。初始化阶段交换功能声明请求-响应循环负责查询和返回结果还支持实时错误反馈。原文说 MCP 像“AI 世界的 USB-C 接口”这个类比很准确但 USB-C 也有代价线材、供电、协议版本、设备角色都要对上。实际部署时你至少要同时确认四件事Codex 的模型请求能出去MCP 服务器能被 Codex 启动服务器的工具注册成功模型能正确选择并调用工具。模型请求走不通Codex 连“要不要调工具”都判断不了服务器启动失败tools/list就是空工具注册了但参数 schema 写错tools/call会返回错误。链路长所以看起来“部署 MCP 服务器需要技术背景”。1.3 把模型请求先统一到 TaoToken与其在 MCP 配置里反复怀疑协议不如先把模型通道固定下来。Codex 的模型请求走统一 API 后initialize和工具选择都由同一套模型返回变量少一个排查会快很多。你需要的是一个兼容通道Codex 按 OpenAI 风格的 provider 配置填 Base URLKey 从 TaoToken 控制台创建模型 ID 以模型广场当时列表为准。这一步做完Codex 侧的基础请求就稳了。接下来才是 MCP 服务器连接外部 API 的配置文件和工具调用示例。顺序反过来很容易把 401、404 和 MCP 启动超时混在一起最后不知道是模型通道问题还是服务器问题。2. 给 Codex 写 config.tomlmodel_provider 指到 https://taotoken.net/apiCodex 的自定义供应商配置在~/.codex/config.toml。这里不要套 Claude Code 的ANTHROPIC_*环境变量Codex 用的是model_provider、base_url、env_key这一套。先把 Key 准备好再确认模型 ID最后写配置。整个过程不需要改 MCP 服务器代码只改 Codex 的模型入口。2.1 创建 Key 与模型 ID 的确认方式打开 TaoToken 注册并登录在控制台创建 API Key记成YOUR_API_KEY。模型 ID 不要凭记忆写去模型广场看当时的列表把你要用的那个 ID 复制出来占位成YOUR_MODEL_ID。Base URL 填进 Codex 的是https://taotoken.net/api末尾不要加/v1也不要在这个地址后面拼 UTM 参数。如果你后面要在 Codex 会话里跑 MCP 工具调用模型至少要能稳定返回工具调用意图。选一个在模型广场里支持工具调用的 ID别拿纯聊天模型硬试。具体支持情况以模型广场当时列表为准不要编造带日期后缀的模型名。2.2 ~/.codex/config.toml 的可复制配置先备份原文件然后写入下面这段。env_key里的名字是环境变量名不是 Key 本身。wire_api按你的 Codex 版本和通道兼容性选择多数兼容 Chat Completions 的通道用chat如果你的 Codex 版本要求 Responses 协议就按版本文档调整。model YOUR_MODEL_ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat保存后在终端里设置环境变量。macOS 或 Linuxexport TAOTOKEN_API_KEYYOUR_API_KEYWindows PowerShell$env:TAOTOKEN_API_KEYYOUR_API_KEY如果你用~/.codex/auth.json它通常服务于默认 OpenAI provider 的凭据读取走自定义 provider 时以config.toml里的env_key为准。不要把ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN写进 Codex 配置那是另一套工具的环境变量。2.3 先验证模型通道再碰 MCP配置写完后先启动一次 Codex问一个不需要工具的问题比如“用一句话解释 JSON-RPC 2.0 的请求和响应结构”。如果这一步报 401优先检查TAOTOKEN_API_KEY是否真的在当前 shell 里如果报 404检查base_url是不是误写成https://taotoken.net/api/v1或少了/api。模型通道通了再继续加 MCP 服务器。这一步的意义是把问题分域。后面 MCP 服务器启动失败、工具列表为空、工具调用参数不对都能确定是 MCP 侧的事而不是模型请求没出去。3. 让 Codex 按 JSON-RPC 2.0 生成 MCP 服务器配置和工具调用示例MCP 的通信机制原文讲得很清楚初始化、请求-响应、双向通信、动态发现工具。难点不在理解而在写出一个能跑的最小闭环。你可以让 Codex 帮你生成配置和示例但前提是 Codex 自己的模型请求已经走 TaoToken。每轮分析、生成、解释所用的 Token 都由 TaoToken 提供这样你只需要专注校验 MCP 配置。3.1 先让 Codex 解释 initialize / tools/list / tools/call在 Codex 会话里给它一个明确任务按 MCP 官方 JSON-RPC 2.0 规范解释initialize、tools/list、tools/call的请求字段和响应字段并写出最小消息示例。提示词可以这样写请按 MCP 官方 JSON-RPC 2.0 规范解释 initialize、tools/list、tools/call 的请求和响应结构。 然后写一个最小 MCP 服务器示例暴露 get_todo 工具连接 https://jsonplaceholder.typicode.com/todos/{id}。 最后给出 Codex 的 ~/.codex/config.toml 中 mcp_servers 配置片段。 只生成代码和配置不要尝试在本地执行外部命令。注意最后一句。AI 编程工具默认不能直连读者的生产库或生产机器去执行业务操作。这里让它生成、解释、对照代码就够安装依赖、启动 server、发请求都由你在本地做。3.2 写一个连接外部 API 的最小 MCP 服务器在本地新建目录安装官方 SDK。Node 版本建议 18 以上因为下面用到全局fetch。mkdir mcp-external-api cd mcp-external-api npm init -y npm install modelcontextprotocol/sdk zod新建server.jsimport { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; const server new McpServer({ name: external-api-demo, version: 0.1.0, }); server.tool( get_todo, { id: z.number().int().positive().describe(要查询的待办 ID) }, async ({ id }) { const response await fetch(https://jsonplaceholder.typicode.com/todos/${id}); if (!response.ok) { return { content: [{ type: text, text: 外部 API 返回 ${response.status} }], isError: true, }; } const todo await response.json(); return { content: [{ type: text, text: JSON.stringify(todo, null, 2) }], }; } ); const transport new StdioServerTransport(); await server.connect(transport);这个服务器用 stdio 传输Codex 启动它之后会通过标准输入输出发 JSON-RPC 消息。get_todo是工具名id是参数 schema。外部 API 换成你自己的服务时鉴权头、超时、重试要另外加但结构不变。3.3 把 server 注册进 Codex 的 mcp_servers回到~/.codex/config.toml在模型 provider 配置下面追加[mcp_servers.external_api_demo] command node args [/绝对路径/mcp-external-api/server.js]Windows 路径写成C:\\path\\to\\mcp-external-api\\server.js。command最好用绝对路径比如/usr/local/bin/node或C:\\Program Files\\nodejs\\node.exe。Codex 从图形界面或不同 shell 启动时PATH 可能和你终端里不一样用绝对路径能避开command not found。保存后先在终端手动跑一次node /绝对路径/mcp-external-api/server.js没有输出通常是正常的因为 stdio server 在等 JSON-RPC 消息。如果它立刻报错退出先修 server 文件再让 Codex 启动。3.4 工具调用示例与响应结构MCP 客户端和服务器之间传输的是 JSON-RPC 2.0 消息。初始化请求类似这样{ jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: { name: codex, version: 0.1.0 } } }协议版本号请以你安装的 MCP SDK 文档为准。列出工具{jsonrpc:2.0,id:2,method:tools/list,params:{}}调用工具{ jsonrpc: 2.0, id: 3, method: tools/call, params: { name: get_todo, arguments: { id: 1 } } }服务器返回{ jsonrpc: 2.0, id: 3, result: { content: [ { type: text, text: {\n \userId\: 1,\n \id\: 1,\n \title\: \delectus aut autem\,\n \completed\: false\n} } ] } }Codex 作为 Host 和 Client会根据你的自然语言请求决定是否发出tools/call。你要做的是让这条消息真的到达 server并确认返回结果被贴回会话。4. 在 Codex 会话里跑一次真实调用从 tools/list 到 get_todo配置写完不等于跑通。MCP 的价值在动态发现和工具调用必须跑一次真实链路。这个阶段不要急着接复杂数据库先用公开 API 验证配置格式、工具注册、参数传递和错误返回。确认闭环之后再替换成你自己的服务。4.1 启动检查/mcp 与 server 日志重新打开 Codex。如果你的 Codex 版本支持/mcp命令输入/mcp查看已注册的 MCP 服务器列表确认external_api_demo在列表里。如果不在检查~/.codex/config.toml的[mcp_servers.external_api_demo]是否拼写正确args里的路径是否存在。部分 Codex 版本会把 MCP 启动日志写到会话日志或本地日志文件。看不到工具时先在终端手动运行 server再用一个最小 JSON-RPC 消息测试。比如用echo把tools/list请求管道给 nodeprintf %s\n {jsonrpc:2.0,id:1,method:tools/list,params:{}} | node /绝对路径/mcp-external-api/server.js如果这里能返回工具列表说明 server 没问题问题在 Codex 配置或启动环境。如果这里没返回先修 server。4.2 发起一次工具调用在 Codex 会话里输入请调用 external_api_demo 的 get_todo 工具查询 id1并把原始 JSON 结果贴出来。Codex 会先判断是否需要工具。它可能先发tools/list再发tools/call。你要观察的是会话里是否出现工具调用请求参数是否传成{id:1}结果是否按 MCP content 结构返回。如果 Codex 直接编了一个答案没有调用工具就在提示词里更明确地写“必须使用工具不要直接回答”。如果返回isError: true或数据库类错误不要让它去连生产库执行修复。正确做法是让 Codex 解释错误、生成检查命令或 SQL你在本地或测试库执行再把结果贴回对话。MCP 服务器只是标准化通道不是绕过权限的入口。4.3 确认返回结果与模型 Token 消耗当get_todo返回userId、id、title、completed几个字段时闭环就跑通了。接着打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_mcp 看这次会话的用量记录。模型请求走 TaoTokenMCP 服务器只负责外部 API 调用两者在日志里要分得开模型 Token 看 TaoToken 控制台外部 API 状态码看 server 日志。这一步同时验证了两件事Codex 的base_url和 Key 没问题MCP 服务器的 JSON-RPC 交互也没问题。后面换模型 ID、换外部 API、加更多工具都是在这个基础上做增量。5. 常见报错对照command not found、401、404 与 MCP 超时MCP 配置的报错看起来杂其实可以按层拆。Codex 侧管模型请求和 MCP 启动server 侧管工具注册和外部 API 请求。先看报错出现在哪一层再决定改config.toml还是改server.js。5.1 Codex 侧报错command not found通常发生在 Codex 找不到node。把[mcp_servers.external_api_demo]里的command从node改成which node得到的绝对路径Windows 用where node。如果 Codex 启动后提示模型请求失败先看 401 和 404401 多半是TAOTOKEN_API_KEY没设置或 Key 复制错404 多半是base_url多了/v1正确填写是https://taotoken.net/api。还有一种情况是 Codex 能启动 MCP server但会话里看不到工具。检查tools/list是否返回空数组。如果 server 正常但 Codex 不显示可能是配置节名称大小写不一致或者你改的是另一个config.toml。Codex 的用户级配置通常在~/.codex/config.toml项目级配置可能有覆盖先确认优先级。5.2 MCP server 侧报错server 侧最常见的错误是启动即退出、外部 API 403/404、参数 schema 不匹配。启动即退出时直接在终端运行node server.js看堆栈常见原因是modelcontextprotocol/sdk未安装、Node 版本过低、模块语法没开。外部 API 返回 404 时先手动用curl或浏览器确认 URL 正确再检查 server 里的模板字符串有没有拼错。参数 schema 不匹配时tools/call会返回校验错误。比如id写成了字符串1而 schema 要求 number。Codex 一般会按 schema 传参但自然语言描述不清晰时也可能出错。把工具描述写具体比如“id 是正整数”能减少来回试错。5.3 回到控制台看用量模型通道和 MCP 通道都跑通后回到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_mcp 看控制台记录。重点看三件事这次 Codex 会话消耗了多少 Token用的模型 ID 是不是你写在config.toml里的那个Key 有没有被其他项目复用。如果用量突然上涨先检查是不是某个 MCP 工具触发了多轮工具调用而不是急着换 Key。TaoToken 在这里的角色是统一 API 入口不是 MCP 服务器本身。MCP 服务器仍然由你本地启动、由 Codex 连接TaoToken 只负责模型请求的兼容通道。这个边界分清排障时就不容易把两边的问题混在一起。6. 跑通之后把 MCP 配置沉淀成模板最小闭环跑通后不要把配置留在临时目录。把server.js、config.toml片段、测试用的 JSON-RPC 消息整理成一个可复用模板。下次接新的外部 API只改工具名、参数 schema 和请求地址Codex 侧配置基本不动。这样 MCP 的“一次集成复用性强”才真正落到你的工作流里。6.1 把外部 API 换成你自己的内部 API 时注意什么替换get_todo时先把鉴权、超时、错误结构补上。不要把生产库密码写进server.js明文也不要把server.js做成能执行任意 SQL 的工具。如果内部 API 需要 Key用环境变量传给 MCP server比如在[mcp_servers.external_api_demo.env]里设置而不是写死在代码里。如果工具涉及查询数据库只让 Codex 生成或解释 SQL由你在本地或测试库执行再把结果贴回对话。MCP 服务器可以封装只读查询接口但不要在提示词里让它直连生产库执行DELETE、UPDATE或存储过程。权限控制和审计要在服务端做协议标准化不等于权限放开。6.2 下一步用同一把 Key 做更多验证MCP 配置稳定后可以先去 TaoToken 模型对话 用同一把 Key 发一条消息确认模型 ID 和 Base URL 没填错。若要长期跑 Codex 和多个 MCP 工具可以打开 Coding Plan 看套餐是否够用新的 API Key 在 控制台 API Keys 创建。最后提醒一句MCP 服务器配置文件、Codex 的config.toml、TaoToken 控制台里的用量记录这三处要能互相对上。对不上时先确认模型请求走的是https://taotoken.net/api再确认 MCP server 是用绝对路径启动的最后才去看 JSON-RPC 消息体。把这条链路跑顺比急着堆更多 MCP 服务器更有价值。