Codex MCP 文档翻译教程：本地 stdio 桥接、4 个生产工具与 20 MB 边界

在 Codex 里读文档和“交付一份翻译后的完整文件”是两件事。前者可以直接做摘要、问答或局部翻译后者还需要处理文件上传、异步任务、状态查询、credits 计费和结果下载。对于 PDF、DOCX、PPTX、XLSX 这类完整文档更适合把专业文档处理服务通过 MCP 接进 Codex而不是让模型只返回一段纯文本。下面以翻译排版大师 MCP 为例说明当前已经在生产环境验证过的接入方式。1. 为什么使用本地 stdio 桥接线上 MCP 地址是https://www.fanyipaiban.com/translate/mcpCodex 可以连接 MCP 服务。当前推荐在本机运行一个 Node.js 18 的 stdio 桥接由桥接读取 Codex 发出的 JSON-RPC 消息附加 Bearer API Key 后转发到线上 MCP 地址。这种方式的优点是Codex 仍按本地 stdio 服务管理 MCP。API Key 不需要写进业务项目或公开代码。可以避免不同桌面启动方式导致的环境变量继承差异。MCP 配置、文件读取和后续任务查询都留在同一个 Codex 工作区中。需要明确一个安全边界安装后API Key 会以明文 JSON 保存在当前用户的~/.fanyipaiban/mcp.json。这个目录不能同步到网盘、提交到 Git也不能出现在截图或录屏中。建议为 Codex 单独创建一个可撤销的 API Key。2. 当前线上实际开放的 4 个工具截至 2026-07-17生产 MCP 的tools/list已验证开放以下 4 个工具translation_get_account translation_get_pricing translation_create_document_task translation_get_task它们分别负责translation_get_account读取共享 credits 账户的可用、冻结、已使用和累计充值数据。translation_get_pricing读取当前每计费页 credits以及 PDF、DOCX、PPTX、XLSX 的计费单位。translation_create_document_task提交文件并创建异步翻译任务。translation_get_task按task_id查询状态、进度、费用和短时有效的结果地址。这里特意只列生产环境已经开放的工具。尚未部署到线上 MCP 的本地开发能力不应提前写进教程或宣传材料。3. 先做只读连接检查配置完成并重启 Codex 后不要立刻提交正式文件。先让 Codex 调用两个只读工具1. 调用 translation_get_account概括账户字段不暴露任何密钥。 2. 调用 translation_get_pricing报告当前每计费页 credits以及四种文档分别按什么计费。 3. 不创建任务不修改本地文件。这一步可以同时验证 MCP 注册、API Key 和当前计费规则。截至 2026-07-17页面核验到的规则是 1,500 credits / 计费页但正式接入不要把这个数字永久写死应该以translation_get_pricing的实时响应为准。4. 一份文档的完整执行过程一条合格的 Codex 任务说明至少要明确文件、目标语言、轮询终止条件和结果位置。例如请使用翻译排版大师 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查询。5. MCP 和 REST API 怎么选MCP 更适合以下情况文件已经在 Codex 工作区中。一次处理一份或几份本地文档。翻译完成后还要继续做摘要、术语核对或内容整理。希望用自然语言发起并追踪任务。REST API 更适合以下情况后台系统、RPA、队列或批量流程发起任务。单份本地文件超过 20 MB。需要 multipart 上传、幂等键、重试、日志和结果归档。需要由业务系统长期保存任务状态。两者不是替代关系。MCP 面向 AI 工作区REST API 面向系统集成它们与网页工作台共享同一个 credits 账户。6. 结果仍然需要按业务标准复核支持完整文档任务不等于所有复杂文件都能省略人工检查。扫描件、复杂表格、图片页、公式、金额、型号、单位和专业术语都应该使用代表性样本验证并在正式交付前抽样复核。完整安装步骤、手动配置、故障排查和可直接使用的 Codex 提示词见完整 MCP 接入教程