1. 为什么要在 Codex 里接一个文档翻译 MCP如果你用 Codex 处理过文档大概率遇到过这个尴尬让它读一份 PDF 做摘要、问答、局部翻译都很顺但你说“把这份 30 页的 DOCX 翻成中文排版别乱”它只能给你返回一段纯文本。表格没了页眉页脚没了图片位置也乱了。原因不复杂。Codex 本身是围绕代码和文本工作的它擅长的是“理解内容”而不是“交付一份完整文件”。一份完整文档的翻译背后其实是一整条流水线文件上传、异步任务创建、状态轮询、credits 计费、结果下载。这些动作靠模型返回一段文字是做不到的。MCPModel Context Protocol就是补上这一环的东西。它让 Codex 能调用外部工具把“读文档”和“交付翻译后的完整文件”拆成两件事分别处理。对于 PDF、DOCX、PPTX、XLSX 这类带排版的文档正确做法不是让模型硬啃而是把专业文档处理服务通过 MCP 接进 Codex。这篇面向 Node.js 开发者讲清楚三件事本地 stdio 桥接怎么配、4 个生产工具怎么调、20 MB 文件边界怎么验证。配置骨架可以直接复制工具调用示例可以直接跑。适合谁看已经在用 Codex 做开发、手头有文档翻译需求、愿意在本机跑一个 Node.js 18 桥接的开发者。如果你只是想翻译一段文字不需要往下看如果你要交付完整文件这篇就是给你写的。2. 前置准备TaoToken 与本地 stdio 桥接先说清楚整体架构不然后面配置容易懵。Codex 支持连接 MCP 服务。当前推荐的方式是在本机跑一个 Node.js 18 的 stdio 桥接进程Codex 通过标准输入输出和这个桥接进程通信桥接进程读取 Codex 发出的 JSON-RPC 消息附加 Bearer API Key 后转发到线上 MCP 地址。为什么绕这一层而不是让 Codex 直连线上地址三个实际原因第一Codex 仍然按本地 stdio 服务来管理 MCP行为可预期不依赖网络地址的稳定性。第二API Key 不需要写进业务项目或公开代码只存在本机桥接的配置里。第三可以避免不同桌面启动方式导致的环境变量继承差异——这个坑我踩过GUI 启动和终端启动拿到的环境变量经常不一样。这里要提一下 TaoToken。它提供统一的 API 接入能力模型对话、API Key 管理、接入文档都在一个控制台里。你可以在 TaoToken 控制台创建一个专门给 Codex 用的 API Key后续桥接进程用它做鉴权。相关入口模型对话https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_mcp_doc_translateutm_campaignrewriteAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_mcp_doc_translateutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_mcp_doc_translateutm_campaignrewrite控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_mcp_doc_translateutm_campaignrewriteAPI 基础地址是 https://taotoken.net/api 注意这个地址不带 UTM 参数配置里直接写这个。一个必须强调的安全边界安装后API Key 会以明文 JSON 保存在当前用户的~/.fanyipaiban/mcp.json。这个目录不能同步到网盘不能提交到 Git也不能出现在截图或录屏里。建议为 Codex 单独创建一个可撤销的 API Key用完随时能吊销不要复用生产环境的 Key。3. 可复制配置config.toml 骨架与桥接脚本这一节是全文最核心的部分配置直接给全。3.1 目录结构与依赖先建目录装依赖。桥接进程只需要一个能发 HTTP 请求的运行时Node.js 18 自带 fetch不用额外装 axios。mkdir -p ~/.fanyipaiban cd ~/.fanyipaiban npm init -y npm pkg set typemodule目录约定~/.fanyipaiban/ ├── mcp.json # API Key 与线上地址明文勿外泄 ├── bridge.mjs # stdio 桥接脚本 └── package.json3.2 mcp.json 配置{ endpoint: https://www.fanyipaiban.com/translate/mcp, apiKey: 把你的_TaoToken_API_Key_填在这里, timeoutMs: 60000 }endpoint是线上 MCP 地址apiKey换成你在 TaoToken 控制台创建的那个 Key。timeoutMs是单次转发超时文档任务创建可能稍慢给到 60 秒比较稳。3.3 bridge.mjs 桥接脚本这个脚本做三件事从 stdin 读 JSON-RPC 消息、附加 Bearer 头转发到线上地址、把响应写回 stdout。注意 stdout 只能写协议消息日志一律走 stderr否则会污染 JSON-RPC 流。import { readFileSync } from node:fs; import { homedir } from node:os; import { join } from node:path; const cfgPath join(homedir(), .fanyipaiban, mcp.json); const cfg JSON.parse(readFileSync(cfgPath, utf8)); function log(...args) { process.stderr.write([bridge] args.join( ) \n); } async function forward(payload) { const controller new AbortController(); const timer setTimeout(() controller.abort(), cfg.timeoutMs); try { const res await fetch(cfg.endpoint, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${cfg.apiKey}, }, body: JSON.stringify(payload), signal: controller.signal, }); if (!res.ok) { log(upstream status, res.status); throw new Error(upstream ${res.status}); } return await res.json(); } finally { clearTimeout(timer); } } let buffer ; process.stdin.setEncoding(utf8); process.stdin.on(data, async (chunk) { buffer chunk; let idx; while ((idx buffer.indexOf(\n)) 0) { const line buffer.slice(0, idx).trim(); buffer buffer.slice(idx 1); if (!line) continue; try { const msg JSON.parse(line); const result await forward(msg); process.stdout.write(JSON.stringify(result) \n); } catch (err) { log(handle error, err.message); process.stdout.write( JSON.stringify({ jsonrpc: 2.0, id: null, error: { code: -32000, message: err.message }, }) \n ); } } }); log(bridge ready, endpoint , cfg.endpoint);3.4 Codex 的 config.toml 骨架在 Codex 的配置里注册这个 stdio 服务。路径按你的实际安装位置调整command指向 nodeargs指向桥接脚本。[mcp_servers.fanyipaiban] command node args [/Users/你的用户名/.fanyipaiban/bridge.mjs] env { NODE_NO_WARNINGS 1 }Windows 下把args里的路径换成C:\\Users\\你的用户名\\.fanyipaiban\\bridge.mjs反斜杠要转义。配置保存后重启 Codex让 MCP 服务重新加载。4. 4 个生产工具调用示例与验证截至 2026-07-17生产 MCP 的tools/list已验证开放以下 4 个工具。这里只列生产环境已经开放的尚未部署到线上的本地开发能力不写进来避免你照着调却报 method not found。工具名作用是否只读translation_get_account读取共享 credits 账户的可用、冻结、已使用、累计充值是translation_get_pricing读取每计费页 credits 及四种文档的计费单位是translation_create_document_task提交文件并创建异步翻译任务否translation_get_task按 task_id 查询状态、进度、费用和结果地址是4.1 先做只读连接检查配置完成并重启 Codex 后不要立刻提交正式文件。先让 Codex 调用两个只读工具验证 MCP 注册、API Key 和当前计费规则是否都正常。给 Codex 的提示词可以这样写请调用 fanyipaiban MCP 的两个只读工具 1. translation_get_account概括账户字段不要暴露任何密钥。 2. translation_get_pricing报告当前每计费页 credits以及 PDF、DOCX、PPTX、XLSX 分别按什么计费。 不要创建任务不要修改本地文件。这一步能同时验证三件事MCP 是否注册成功、API Key 是否有效、当前计费规则是什么。截至 2026-07-17页面核验到的规则是 1,500 credits / 计费页但正式接入不要把这个数字永久写死应该以translation_get_pricing的实时响应为准。计费规则会调整写死迟早出问题。4.2 创建文档翻译任务只读检查通过后再提交正式文件。一条合格的 Codex 任务说明至少要明确文件、目标语言、轮询终止条件和结果位置。示例请使用 fanyipaiban MCP把当前工作区的 ./manual.pdf 翻译为中文。 要求 1. 先确认文件存在且不超过 20 MB超过后停止并建议改用 REST API。 2. 调用 translation_create_document_tasksource_langautotarget_langcn。 3. 保存 task_id每 3 至 5 秒调用 translation_get_task。 4. 状态为 SUCCESS 后保存结果无法直接下载时返回短时有效的下载地址。 5. 不覆盖原文件并报告预估和实际 credits。 6. 交付前提醒复核扫描识别、表格、示意图和业务关键数值。真实执行链路是读取本地文件 - 创建异步任务 - 保存 task_id - 查询 QUEUED / RUNNING / SUCCESS / FAILED - 获取结果 - 按交付标准复核这里有个高频错误不要在任务仍为 QUEUED 或 RUNNING 时重复创建新任务。应该继续用同一个 task_id 查询。重复创建会多扣 credits而且你拿到的是一堆并行任务最后不知道哪个是你要的。4.3 查询任务状态translation_get_task是轮询的核心。状态机大致是 QUEUED、RUNNING、SUCCESS、FAILED 四态。轮询间隔 3 到 5 秒比较合适太密会给服务端压力太疏交付慢。请用同一个 task_id 继续查询 translation_get_task 直到状态为 SUCCESS 或 FAILED。 SUCCESS 时报告进度、实际 credits 和结果地址 FAILED 时报告错误码和错误信息不要自动重试。结果地址是短时有效的拿到后尽快下载或转存别放着过夜。5. 20 MB 边界验证与常见报错排查5.1 20 MB 边界怎么验证MCP 通道适合处理已经在 Codex 工作区里的本地文档但单份文件有大小边界。超过 20 MB 的文件建议改用 REST API走 multipart 上传、幂等键、重试和结果归档那一套。验证动作很简单在提交前先让 Codex 检查文件大小# 查看文件字节数 wc -c ./manual.pdf # 或者用 ls 看人类可读大小 ls -lh ./manual.pdf如果超过 20 MB任务说明里要明确让 Codex 停止并建议改用 REST API而不是硬传。硬传的结果通常是超时或上游拒绝排查起来更费时间。5.2 常见报错与排查路径报错一method not found说明你调用的工具名不在生产环境已开放的 4 个工具里。对照第 4 节的表格只调translation_get_account、translation_get_pricing、translation_create_document_task、translation_get_task。本地开发中的能力不要提前写进提示词。报错二401 或鉴权失败检查~/.fanyipaiban/mcp.json里的apiKey是否和 TaoToken 控制台里创建的一致有没有多余空格。如果 Key 被吊销过重新创建一个。注意桥接脚本里拼的是Bearer ${cfg.apiKey}中间是一个空格。报错三桥接进程启动即退出多半是 stdout 被日志污染了。检查bridge.mjs里所有日志是否都走了process.stderr.writestdout 只写 JSON-RPC 响应。另外确认 Node.js 版本是 18 以上低版本没有全局 fetch。报错四任务一直 RUNNING 不结束先确认文件大小没超边界再确认轮询用的是同一个 task_id。如果长时间卡住查translation_get_task返回的进度字段必要时报告错误码不要自动重试创建新任务。报错五结果地址打不开结果地址是短时有效的过期后需要重新查询任务或重新创建。拿到地址后立即下载不要延迟处理。6. MCP 还是 REST API以及后续怎么走两者不是替代关系是面向不同场景的两条路。MCP 更适合文件已经在 Codex 工作区里、一次处理一份或几份本地文档、翻译完还要继续做摘要或术语核对、希望用自然语言发起并追踪任务。REST API 更适合后台系统、RPA、队列或批量流程发起任务、单份本地文件超过 20 MB、需要 multipart 上传和幂等键、需要业务系统长期保存任务状态。它们与网页工作台共享同一个 credits 账户所以计费口径是一致的不用担心两边对不上。最后提醒一句支持完整文档任务不等于所有复杂文件都能省略人工检查。扫描件、复杂表格、图片页、公式、金额、型号、单位和专业术语都应该用代表性样本先验证正式交付前抽样复核。这一步省不得尤其是涉及业务关键数值的文档。如果你要长期在 Codex 里做编码和 Agent 类任务可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcodex_mcp_doc_translateutm_campaignrewrite 。接入过程中遇到鉴权或工具调用问题优先查 API Key 管理和接入文档两个入口比在群里问快得多。