codex-mcp-bridge

English version

MCP server for Claude Desktop to send prompts directly into an existing Codex thread, through a shared Codex app-server. Runs on macOS, Windows, and Linux.

Not codex exec (which creates a new session every time). The bridge speaks JSON-RPC with the real Codex app-server, so the thread keeps its history, cwd, model, and rollout file.

Architecture

Claude Desktop ──stdio──> codex-mcp-bridge ──WebSocket──> codex app-server (ws://127.0.0.1:8791)
                                                                  │
Codex TUI  ──codex --remote ws://127.0.0.1:8791───────────────────┘   (cùng app-server, cùng thread live)

• The app-server is a singleton per port. The bridge probes http://127.0.0.1:8791/readyz; if it is not alive, it spawns a detached one (codex app-server --listen ws://127.0.0.1:8791), and that app-server keeps running independently after the bridge exits.

• Every client pointing to the same URL uses the same app-server → thread/resume with threadId rejoins the actual running thread instead of starting a new session.

• The bridge keeps exactly one WebSocket, initializes once, and routes notifications by threadId, so multiple threads running in parallel never interfere with each other.

Related MCP server: webgpt MCP

Tools

send_to_codex_thread accepts additional timeoutSec (default 240), cwd, model, effort, and openInApp (macOS — opens the thread in the app before sending so you can watch live). Timing out does not cancel the turn — the bridge returns whatever it has gathered along with turnId; continue reading with read_codex_thread or stop with interrupt_codex_turn.

Install into Claude Desktop

npm install
node scripts/install-claude-desktop.mjs

The script detects the platform, creates the config file if it doesn't exist, backs up the old one (*.bak-<ngày>-codexbridge), and preserves all existing keys:

Result on macOS:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "/Users/<user>/.local/node/v24.18.0/bin/node",
      "args": ["/Users/<user>/code/codex-mcp-bridge/src/index.mjs"],
      "env": {
        "CODEX_BIN": "/Users/<user>/.local/bin/codex",
        "CODEX_APP_SERVER_URL": "ws://127.0.0.1:8791"
      }
    }
  }
}

Restart Claude Desktop after installing.

Resolve the codex binary: Claude Desktop (and launchd) launch the MCP server with a trimmed PATH, so codex is often not on PATH. The bridge searches in this order — CODEX_BIN → the platform's usual install locations → PATH:

On macOS/Linux, codex is a Node script with shebang #!/usr/bin/env node, so the bridge also injects PATH (current node directory + /opt/homebrew/bin + /usr/local/bin + system dirs) into child processes — without this step, spawning the app-server dies immediately at the shebang.

macOS

Run the app-server in the background with launchd

node scripts/install-launch-agent.mjs

Create ~/Library/LaunchAgents/com.codex-mcp-bridge.app-server.plist (RunAtLoad + KeepAlive on crash, ThrottleInterval 10s) then launchctl bootstrap gui/$UID. The app-server is already alive from login, so the bridge doesn't have to spawn it, and threads are always in the live state.

launchctl print gui/$UID/com.codex-mcp-bridge.app-server | head -20   # trạng thái
node scripts/install-launch-agent.mjs --uninstall                     # gỡ

Log: ~/Library/Logs/codex-mcp-bridge/app-server.{out,err}.log.

View threads directly in the Codex desktop app

The Codex desktop app on macOS is /Applications/ChatGPT.app and registers the codex:// scheme. The bridge uses codex://threads/<threadId> to open the correct thread:

open_codex_thread { threadId: "01a0…", background: true }
send_to_codex_thread { threadId: "01a0…", prompt: "…", openInApp: true }

This is how the person assigning the task can watch Codex doing the work instead of having to read back the rollout ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl after it finishes.

Limitations on macOS

• The Codex desktop app runs its own app-server via stdio (ChatGPT.app/Contents/Resources/codex … app-server) and does not accept an external endpoint. Threads opened in the app can still be sent to via the bridge, but by resuming from the .jsonl rollout rather than attaching live. Do not send to a thread currently running a turn in the desktop app — two app-servers writing to the same rollout can corrupt the history. Check status with list_codex_threads first, and only send when idle/notLoaded.

• A repo on an NTFS partition of a dual-boot machine (/Volumes/...) is read-only on macOS — macOS mounts NTFS read-only. Keep a separate checkout on an APFS volume (e.g. ~/code/codex-mcp-bridge) to run and edit.

• codex app-server daemon start uses unix:// transport with control socket ~/.codex/app-server-control/app-server-control.sock. The bridge does not use this path (a framing protocol different from WebSocket, and no public API yet) — it always talks over ws://.

Environment

About approval: Codex will ask to approve commands/patches if approval_policy is not never. No one is sitting in front of Claude Desktop to click, so the bridge automatically answers according to CODEX_BRIDGE_APPROVAL and logs to stderr. The default approve matches the configuration approval_policy = "never" + sandbox_mode = "danger-full-access" in ~/.codex/config.toml; if you tighten the sandbox, consider switching to deny.

Sharing the app-server with an interactive Codex session

Open the TUI pointing at the same endpoint so threads in the TUI and the bridge see them as one:

codex --remote ws://127.0.0.1:8791

Run the app-server manually (independent of bridge autostart):

codex app-server --listen ws://127.0.0.1:8791

Testing

npm run check

Quick check: the bridge starts, autostarts the app-server if needed, lists threads.

npm run smoke

Smoke test creates a new thread, sends 2 consecutive turns, and verifies Codex remembers the codeword from the previous turn — i.e., the thread is truly continuous rather than a new session each time.

Check the environment from inside Claude: call the codex_bridge_status tool.