Codex MCP Server：把 Codex CLI 接入多代理工作流

适用场景

这篇手册面向高级用户。你已经会使用 Codex CLI，现在想让其他代理框架或 MCP 客户端调用 Codex，把它变成一个可编排的软件开发工具。

典型场景包括：

• 一个规划代理把任务拆解后交给 Codex 实现。
• 一个审查代理调用 Codex 修改局部代码。
• 团队把 Codex 作为 CI 或内部平台的一部分。
• 使用 Agents SDK 编排多个角色、handoff、guardrails 和 traces。

基本原理

Codex CLI 可以作为 MCP server 运行：

codex mcp-server

其他 MCP 客户端连接后，可以发现 Codex 暴露的工具。官方文档中提到的核心思路是：用一个工具启动 Codex 会话，再用另一个工具继续同一个线程。

这样做的好处是，外部系统可以把 Codex 当成一个可调用的开发代理，而不是只能由人手动在终端里输入。

步骤 1：确认前置条件

先准备：

• 已安装 Codex CLI，并且 codex 命令可用。
• 已完成登录或配置 API key。
• 了解审批策略和沙箱模式。
• 如果使用 Agents SDK，准备 Python 3.10+。
• 如果使用 MCP Inspector，准备 Node.js 18+。

先在终端里确认：

codex --version

再确认普通 Codex CLI 任务能运行。

步骤 2：启动 MCP server

最小启动命令：

codex mcp-server

如果想用 MCP Inspector 检查工具列表，可以运行：

npx @modelcontextprotocol/inspector codex mcp-server

这一步的目标是确认 MCP 客户端能看到 Codex server，以及工具 schema 能被读取。

步骤 3：理解可传参数

通过 MCP 调用 Codex 时，常见参数包括：

| 参数 | 用途 | | --- | --- | | prompt | 启动或继续任务的用户提示 | | cwd | Codex 工作目录 | | model | 指定模型 | | approval-policy | 审批策略 | | sandbox | 沙箱模式 | | config | 覆盖 config.toml 中的部分配置 | | profile | 指定配置 profile |

自动化场景中最重要的是 cwd、approval-policy 和 sandbox。不要在没有审查的流水线里直接使用高权限模式。

步骤 4：在 Agents SDK 中连接

官方示例展示了用 Agents SDK 的 MCP 集成启动 Codex server。概念上可以理解为：

from agents.mcp import MCPServerStdio

codex_mcp_server = MCPServerStdio(
    name="Codex CLI",
    params={
        "command": "codex",
        "args": ["mcp-server"],
    },
)

然后把这个 MCP server 交给某个开发代理使用。实际生产代码应继续补充超时、日志、错误处理和审计。

步骤 5：设计安全边界

多代理工作流很容易把错误放大，所以要先设计边界：

• 限定 cwd 到临时工作区或专用仓库。
• 默认使用 workspace-write 或更严格沙箱。
• 对 shell、网络和文件写入保留审批。
• 对自动生成的 patch 做二次审查。
• 对每个任务保存 trace、日志或结构化结果。
• 禁止把密钥写入 prompt、代码或日志。

如果这个流程会接入 CI，建议先只运行只读分析任务，再逐步开放写入。

常见错误

不要把 MCP Server 当成绕过 Codex 审批的后门。审批、沙箱和权限仍然应该保留。

不要让外部代理给 Codex 传无限制的大任务。多代理系统更需要明确输入、输出和停止条件。

不要忽略 thread ID。继续同一个 Codex 会话时，需要保存并传递线程标识。

小结

Codex MCP Server 适合把 Codex CLI 纳入更大的自动化和多代理体系。正确做法是先让 codex mcp-server 稳定运行，再用 MCP 客户端连接，最后围绕审批、沙箱、工作目录和审计设计安全工作流。