在 Codex 里读文档和“交付一份翻译后的完整文件”是两件事。

前者可以直接做摘要、问答或局部翻译；后者还需要处理文件上传、异步任务、状态查询、credits 计费和结果下载。对于 PDF、DOCX、PPTX、XLSX 这类完整文档，更适合把专业文档处理服务通过 MCP 接进 Codex，而不是让模型只返回一段纯文本。

下面以翻译排版大师 MCP 为例，说明当前已经在生产环境验证过的接入方式。

1. 为什么使用本地 stdio 桥接

线上 MCP 地址是：

https://www.fanyipaiban.com/translate/mcp

Codex 可以连接 MCP 服务。当前推荐在本机运行一个 Node.js 18+ 的 stdio 桥接，由桥接读取 Codex 发出的 JSON-RPC 消息，附加 Bearer API Key 后转发到线上 MCP 地址。

这种方式的优点是：

1. Codex 仍按本地 stdio 服务管理 MCP。
2. API Key 不需要写进业务项目或公开代码。
3. 可以避免不同桌面启动方式导致的环境变量继承差异。
4. 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_task，source_lang=auto，target_lang=cn。
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 接入教程