Codex Supervisor MCP

一个本地 Model Context Protocol (MCP) 桥接器，允许兼容的主机启动、监控、引导、中断、恢复和批准 Codex 应用服务器的工作。

它包装 codex app-server；它不自动化终端 UI，也不抓取 IDE。

功能

该服务器暴露以下 MCP 工具：

Related MCP server: Codex Bridge MCP

要求

• Node.js 22 或更新版本。

• 当前 Codex CLI 可作为 codex 使用。

• 已配置 Codex CLI 身份验证。

• 一个或多个明确的本地仓库根目录。

本项目没有 npm 运行时依赖。

验证软件包

npm test

测试套件使用与协议兼容的模拟应用服务器。它不发起模型请求，也不需要 Codex 身份验证。

使用 Codex CLI 安装

使用 MCP 服务器名称 codex-supervisor。该名称必须匹配 CODEX_SUPERVISOR_MCP_NAME；桥接器使用它来防止子应用服务器递归加载同一个 MCP 服务器。

macOS 或 Linux

codex mcp add codex-supervisor \
  --env CODEX_ALLOWED_ROOTS="/Users/you/code:/Users/you/work" \
  --env CODEX_SUPERVISOR_MCP_NAME="codex-supervisor" \
  -- node "/absolute/path/to/codex-supervisor-mcp/src/index.mjs"

在根目录之间使用平台路径列表分隔符。在 macOS 和 Linux 上是冒号（:）。

Windows PowerShell

codex mcp add codex-supervisor `
  --env CODEX_ALLOWED_ROOTS="C:\src;D:\work" `
  --env CODEX_SUPERVISOR_MCP_NAME="codex-supervisor" `
  -- node "C:\absolute\path\to\codex-supervisor-mcp\src\index.mjs"

在 Windows 上路径列表分隔符是分号（;）。

确认注册：

codex mcp list

在 Codex 中，键入 /mcp 以检查已连接的服务器。

使用 config.toml 安装

复制并调整 examples/config.toml，然后将其内容放入 ~/.codex/config.toml 或受信任项目的 .codex/config.toml 中。

使用绝对路径。保持服务器 id 和 CODEX_SUPERVISOR_MCP_NAME 相同。

ChatGPT 桌面版或 Codex IDE 扩展

1. 打开 设置 → MCP 服务器 → 添加服务器。

2. 将名称设置为 codex-supervisor。

3. 选择 STDIO。

4. 将命令设置为 node。

5. 将 src/index.mjs 的绝对路径作为唯一参数添加。

6. 添加 CODEX_ALLOWED_ROOTS 和 CODEX_SUPERVISOR_MCP_NAME=codex-supervisor。

7. 保存并重启主机。

8. 键入 /mcp 以验证工具。

普通的 ChatGPT 网页聊天不会加载本地 STDIO MCP 服务器。从网页使用此桥接器需要单独部署的、经过身份验证的远程 MCP 服务或托管插件。

典型工作流程

让 MCP 主机执行：

Use codex_start in /absolute/path/to/repository to implement the requested
change. Use workspaceWrite, keep network access disabled, wait for progress,
show me every approval request before resolving it, and report the final diff
and test result.

主机应按以下顺序操作：

codex_start -> codex_wait
  approval request -> inspect -> codex_resolve_approval -> codex_wait
  active correction -> codex_steer -> codex_wait
  completed -> codex_status
  later follow-up -> codex_send -> codex_wait

每次 start/send/steer/interrupt 调用都会返回一个 eventCursor。将其作为 afterSequence 传递给 codex_wait 或 codex_status，以避免重放较早的事件。

approvalPolicy 接受当前应用服务器线路值 on-request（默认）和 untrusted。桥接器接受旧值 onRequest 和 unlessTrusted，并在应用服务器请求之前将其规范化。

公共批准 API 接受 decline，即使 Codex 应用服务器版本仅为该请求公布 cancel。在这种情况下，桥接器使用安全的应用服务器取消响应，并同时报告请求的决定和实际生效的决定。

配置

默认的应用服务器参数等效于：

-c mcp_servers.<CODEX_SUPERVISOR_MCP_NAME>.enabled=false app-server

覆盖 CODEX_APP_SERVER_ARGS 会移除该递归保护。请自行包含等效的禁用覆盖。

安全模型

• CODEX_ALLOWED_ROOTS 是必需的。

• 路径使用 realpath 进行规范化；拒绝符号链接逃逸。

• Codex 获得对所选仓库和平台默认值的受限读取权限。

• workspaceWrite 将可写根目录限制为所选仓库。

• 不暴露 dangerFullAccess。

• 网络访问需要同时满足 CODEX_ALLOW_NETWORK=1 和任务上的 networkAccess: true。

• 桥接器没有通用的、非沙箱的 shell 工具。

• 命令和文件更改批准必须显式解决。

• 允许根目录之外的线程将被拒绝或过滤。

• 事件负载在存储前有大小限制。

• 存储的线程路径在使用时重新规范化；已删除或替换的仓库路径将安全失败（fail closed）。

• 同线程的变更、批准响应和重试的远程调用会被序列化或去重，而不会执行两次。

• 传输错误在跨越 STDIO 或 HTTP 边界之前会被递归编辑并限制大小。

• 中继和远程服务器凭据（BIOTELE_* 和 CODEX_REMOTE_*）会从子 Codex 环境中移除。

• 远程结果提交经过 HMAC 身份验证、base64url 编码、分块（块大小有界），并在使用前通过长度和 SHA-256 验证。编码保护传输免受内容过滤器的影响；它不是加密。

子应用服务器仍然继承非中继进程设置和您更广泛的 Codex 配置。在与不受信任的代码一起使用之前，请审计其他环境机密、应用程序、技能、钩子和已配置的 MCP 服务器。环境剥离不是操作系统安全边界：以同一 Windows 用户身份运行的子系统可以有意查询用户范围设置。如果该威胁在范围内，请使用专用的 Windows 账户。

支持的批准请求

此版本解决：

• item/commandExecution/requestApproval

• item/fileChange/requestApproval

其他应用服务器请求仍然可以通过 codex_status 和 codex_list_approvals 可见，但桥接器拒绝回应它们。这防止通用响应端点静默授予权限或提供敏感用户输入。

持久化与监控

Codex 拥有持久化的线程历史。桥接器在内存中保留流式事件缓冲区、最新的增量和待处理的请求状态。重启 MCP 服务器会清除该瞬态状态，但 codex_list_threads 和 codex_read_thread 可以恢复已授权的持久化线程。

开发

npm test
node --check src/index.mjs

项目布局：

src/app-server-client.mjs  Codex app-server JSONL client
src/approval-policy.mjs    Approval-policy validation and legacy normalization
src/event-store.mjs        Bounded event, turn, and approval state
src/security.mjs           Repository-root policy
src/supervisor-service.mjs Codex lifecycle orchestration
src/tool-registry.mjs      MCP tool schemas and validation
src/mcp-server.mjs         Dual-era MCP STDIO transport
src/index.mjs              Entrypoint
test/                      Unit and integration tests

许可证

MIT

Codex App Server 兼容性

版本 1.0.3 从 turn/start 中移除了已弃用的 readOnly.access 和 workspaceWrite.readOnlyAccess 字段。当客户端需要自定义受限读取范围时，当前 Codex App Server 版本使用权限配置文件。主管继续将可写根目录限制为所选仓库，并根据 CODEX_ALLOWED_ROOTS 验证每个任务目录。

Hostinger 远程中继

版本 1.2.5 提供了一个与 Hostinger 兼容的中继，用于 ChatGPT 远程 MCP 访问：

ChatGPT -> OAuth bearer JWT -> Hostinger /mcp -> namespace-routed queue
  codex_*  -> outbound Windows local-agent -> Codex app-server
  reeves_* -> outbound Reeves Android agent -> accessibility service

公共 /mcp 端点验证来自外部身份提供者的 RS256 OAuth 访问令牌。Windows 和 Reeves 代理仅对出站轮询、状态、租约获取和结果提交使用独立的 HMAC 凭据。Hostinger 中继从不启动 Codex，也从不读取本地仓库。

托管中继保留所有现有的 codex_* 工具，并额外公开 reeves_status、reeves_tap、reeves_swipe、reeves_type、reeves_back、reeves_home、reeves_recents、reeves_sequence 和 reeves_screenshot。本地 STDIO Codex 注册表仍然仅限 Codex。代理声明按经过身份验证的密钥 ID 过滤；客户端提供的路由字段被忽略。

reeves_screenshot 将 Android 像素作为标准 MCP image 内容块（带有 base64 数据的 image/png）连同宽度、高度、捕获时间戳、代理 id 和字节长度元数据一起返回。Android 代理使用中继公布的块式结果协议，因此不会暴露任何不可用的 Android 本地路径，并且每个签名的 HTTP 请求都保持在中继主体限制内。

reeves_sequence 在一个路由作业中发送 1 到 50 个有序设备操作。Android 在本地执行点击、滑动、输入、返回、主页、最近、等待和截图操作，默认在第一个错误时停止，并默认返回一张最终的 MCP 图像。结果包括索引操作结果和附加的、无秘密的中继/Android 阶段时序。现有的 25 秒代理请求是入队唤醒长轮询，而不是拾取延迟；Android 在每次成功提交结果后立即开始另一个声明，并重用同一个 OkHttp 连接池。

此版本还协商受支持的 MCP 协议版本，发出一个有界的、绑定 OAuth 主题的会话，并要求后续请求使用该会话。重试的工具调用绑定到 OAuth 主题、MCP 会话、类型化 JSON-RPC id 和请求哈希；终止会话会使缓存或待处理的工作失效。该版本还清理已取消的中继工作和崩溃的应用服务器状态，重新验证授权的路径，隔离每个线程的事件，并在每个公共传输中编辑有界的嵌套错误数据。

版本 1.2.5 还使 codex_status.latestAgentMessage 与已授权的持久化记录保持一致。完全持久化的外部 Codex 完成（包括合成的 rollout-* 轮次）现在替换陈旧的桥接器观察到的消息，而不完整或中断的转录尾部仍然被排除。

在更新 Windows 代理之前部署更新的中继。新中继仍然接受传统的一次性结果，而新代理仅在中继公布支持后使用块式格式。

有关 Hostinger hPanel 步骤、mcp.biotele.mx 的 DNS、Auth0 设置、Microsoft Entra ID 设置、ChatGPT Web 连接器设置和恢复、环境变量、本地代理安装以及威胁模型，请参阅 docs/REMOTE_DEPLOYMENT.md。