cc-codex-mcp

A local stdio MCP server that lets Claude Code agents and subagents ask OpenAI Codex for an independent opinion (typically a read-only review of their changes) and follow up on the same Codex thread later.

• codex_ask: start a Codex thread in a project directory and get the answer plus a thread_id.
• codex_followup: continue that thread ("I fixed 1 and 3, re-check").
• Per call: model, effort, fast, sandbox, timeout_sec.
• Runs in an isolated CODEX_HOME (~/.codex-reviews), so these threads never show up in the Codex desktop app.
• Safe for many parallel callers: one process and temp dir per call, no shared state, plus a cross-process lock per thread.
• Windows first (tested on Windows 10 with the Codex desktop app and codex-cli 0.163). macOS/Linux should work but are untested.

Requirements

• Node.js >= 20.3
• The Codex CLI. On Windows it ships with the Codex desktop app; a separately installed codex works too (see How Codex is found).
• A ChatGPT account that can use Codex.

Install

git clone https://github.com/NtTestAlert/cc-codex-mcp.git
cd cc-codex-mcp
npm install
npm run build

1. One-time login for the isolated home

The isolated home has its own login. auth.json is never copied or linked from ~/.codex, because token refreshes rewrite that file.

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File scripts\login.ps1
# or by hand:
$env:CODEX_HOME="$HOME\.codex-reviews"; & "$env:LOCALAPPDATA\Codex\versions\current\resources\codex.exe" login

Add -DeviceAuth (or --device-auth) if no browser can open. On macOS/Linux: CODEX_HOME="$HOME/.codex-reviews" codex login.

Until you log in, every tool call returns an error containing this command.

2. Register with Claude Code (CLI and desktop app)

Claude Code's CLI and the Claude desktop app (Code tab) share the same user-scope MCP config (~/.claude.json), so one registration covers both. Use an absolute path to a real node.exe: version-manager shims (Volta, nvm-windows) can pick a different Node per project, and Volta's shim also mangles </> in arguments.

claude mcp add-json --scope user cc-codex-mcp '{"type":"stdio","command":"C:/path/to/node.exe","args":["C:/path/to/cc-codex-mcp/dist/index.js"],"timeout":3700000}'
claude mcp get cc-codex-mcp

claude mcp get should show Status: ✔ Connected. New Claude Code sessions (CLI or desktop) pick it up; sessions that were already open need a restart. Tools appear as mcp__cc-codex-mcp__codex_ask and mcp__cc-codex-mcp__codex_followup.

Other MCP clients (Claude Desktop chat, Cursor, etc.) use the usual stdio entry: command = absolute node, args = [".../dist/index.js"].

Tool-call timeout

Claude Code has two limits on MCP tool calls (checked in Claude Code 2.1.277 / desktop 2.1.299):

• a hard wall-clock limit: the per-server "timeout" (ms) if set, otherwise MCP_TOOL_TIMEOUT, otherwise about 28 h;
• an idle limit, CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT (default 30 min for stdio), which progress notifications reset.

The per-server "timeout": 3700000 above covers the maximum timeout_sec (3600). It works in both the CLI and the desktop app, regardless of environment-variable precedence (under the desktop app, a variable already in the host's environment wins over settings.json env). The server sends a progress notification every ~15 s while Codex runs, which keeps the idle limit from firing. You don't need to set MCP_TOOL_TIMEOUT; setting it would lower the 28 h default for every server.

3. Tell your agents when to use it

See CLAUDE.snippet.md: drop it into a project's CLAUDE.md. Implementer subagents then get a read-only review when they finish, fix real issues, re-check on the same thread, stop after 3 rounds, and never use fast mode unless told to.

Check the setup

node dist/index.js --doctor

This prints the resolved Codex executable, the isolated home and login state, and the MCP sync report: each server, its transport, and whether default_tools_approval_mode is set. It also creates the isolated home if needed and runs one real config sync, so it may update the isolated config.toml (never ~/.codex).

Tools

codex_ask

input	default
prompt	required	sent on stdin, so no quoting issues
cwd	required	project directory (-C)
sandbox	read-only	or workspace-write
model	config default	-m
effort	config default	low|medium|high|xhigh|max|ultra → -c model_reasoning_effort="…"; checked against the model's supported levels
fast	false	-c service_tier="fast" -c features.fast_mode=true; uses about 2.5x the subscription limits
skip_git_check	false	--skip-git-repo-check
timeout_sec	900	10…3600; on timeout the whole process tree is killed (taskkill /T /F)

Runs codex exec --json --color never -C <cwd> -s <sandbox> [...] -o <temp file> -.

codex_followup

Inputs: thread_id (a UUID, validated, and it must exist in the isolated home), prompt, plus optional model, effort, fast, timeout_sec. Runs codex exec resume --json --skip-git-repo-check -c sandbox_mode="<original>" [...] -o <temp file> <thread_id> -, with the process working directory set to the thread's original cwd. If that directory no longer exists, it runs from your home directory and says so in warnings.

Result (both tools)

{
  "thread_id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "answer": "…",
  "duration_sec": 7.5,
  "warnings": [],
  "activity": { "commands": 2, "mcp_tool_calls": ["openaiDeveloperDocs.search_openai_docs (completed)"], "subagent_events": 0 },
  "error": "…only when something failed…",
  "answer_file": "…only when the answer was truncated…"
}

• answer is the -o file (falling back to the last agent_message), ANSI-stripped and capped at 50,000 characters. When it's longer, the full text stays in answer_file.
• warnings collects MCP server startup failures, failed or rejected MCP tool calls, declined commands, unsupported service tier / fast-mode messages, config problems, and config-sync errors.
• On turn.failed, error events in a turn that didn't complete, a non-zero exit, a timeout or cancellation, error holds the message plus the last 40 stderr lines. Any partial answer and the thread_id are still returned.
• activity is only present when Codex ran commands, called MCP tools, or spawned subagents.

Environment variables

variable	default
CODEX_BRIDGE_HOME	~/.codex-reviews	isolated CODEX_HOME; refused if it resolves to the main home
CODEX_BRIDGE_SOURCE_HOME	~/.codex	main Codex home (source of truth for config and sandbox state)
CODEX_BRIDGE_CODEX_PATH	auto	explicit Codex executable (.exe, .js, or an npm .cmd/.ps1 shim to unwrap)
CODEX_BRIDGE_COPY_CONFIG	unset	1 = copy ~/.codex/config.toml once if the isolated home has none
CODEX_BRIDGE_MCP_EXCLUDE	unset	comma-separated MCP server names not to sync
CODEX_BRIDGE_SYNC_DESKTOP_ONLY	unset	1 = also sync desktop-only servers such as node_repl

How Codex is found

1. CODEX_BRIDGE_CODEX_PATH.
2. codex on PATH. An npm codex.cmd shim is unwrapped to the native codex.exe inside the npm package, or to bin/codex.js run with the current Node. A shell is never used.
3. The desktop app: %LOCALAPPDATA%\Codex\versions\current\resources\codex.exe (current is a junction to the newest version), else the highest versions\<x.y.z.w> folder. On macOS, /Applications/Codex.app/Contents/Resources/codex.

What is shared with the Codex desktop app

The desktop app's ~/.codex is the source of truth. The bridge only reads it and only writes the isolated home.

Config sync (config.toml): at startup, then when ~/.codex/config.toml changes (fs.watch, debounced 1 s), plus a cheap mtime/size check before each run in case the watcher missed an event. The sync copies:

• the [mcp_servers.*] tables (per server name the source wins; servers only in the isolated config are kept; servers removed from the source are removed again);
• top-level model and model_reasoning_effort;
• the [windows] table. Without windows.sandbox, Codex on Windows blocks every shell command in read-only mode, even git diff.

All other isolated-config keys are kept. Writes are atomic and only happen when the synced subset actually changed. The file is parsed with a real TOML parser (smol-toml), so comments in the isolated config are not preserved. Desktop-only servers are skipped by default (node_repl needs the desktop app's named pipe and hard-codes CODEX_HOME=~/.codex).

Elevated Windows sandbox state. The elevated sandbox runs commands as two machine-wide local accounts (CodexSandboxOffline / CodexSandboxOnline). Each CODEX_HOME keeps its own DPAPI-encrypted copy of their passwords (.sandbox-secrets/sandbox_users.json) and a .sandbox/setup_marker.json. If two homes each provision, every provisioning rotates the passwords and makes the other home re-run the elevated setup, endlessly. So the desktop app's home owns this state, and the bridge copies those two files into the isolated home at startup and whenever the desktop app rewrites them (fs.watch). Nothing happens per call. The isolated home never provisions while the desktop app has a provisioned sandbox, and ~/.codex is never written.

Normal Codex behaviour is unaffected: a quick, non-elevated codex-windows-sandbox-setup.exe "setup refresh" still runs before sandboxed commands, as it does in the desktop app.

Not shared: auth.json (separate login), MCP OAuth tokens (see below), sessions/threads, history, memories.

Tool approvals for synced MCP servers

node dist/index.js --doctor lists every synced server and whether it sets default_tools_approval_mode = "approve". The bridge never changes that setting. In testing, read-only MCP tools ran fine under exec without it. If a server's tool calls get rejected for approval, warnings says so; add default_tools_approval_mode = "approve" to that server in ~/.codex/config.toml and the sync carries it over.

MCP OAuth tokens

With Codex 0.163 on Windows, OAuth tokens for remote MCP servers are stored per CODEX_HOME: CODEX_HOME\secrets\mcp_oauth.age, with its key in Windows Credential Manager under an account derived from the CODEX_HOME path. The isolated home does not see the desktop app's tokens. To log a server in for the isolated home:

$env:CODEX_HOME="$HOME\.codex-reviews"; & "$env:LOCALAPPDATA\Codex\versions\current\resources\codex.exe" mcp login <server>

Remote plugins enabled on your ChatGPT account are installed into every home, including the isolated one, so their OAuth MCP servers need this login too. Until a server is logged in, each run carries a harmless AuthRequired warning for it. Servers that authenticate with headers or bearer_token_env_var in config.toml need nothing extra.

Verified against the installed CLI (codex-cli 0.163.0-alpha.10.2)

• exec: --json, -o, -C, -s read-only|workspace-write|danger-full-access, -m, -c key=value (TOML value), --skip-git-repo-check, and - / no prompt = read stdin all exist. The first JSON event is {"type":"thread.started","thread_id":…}. Thread ids are UUIDv7.
• exec resume: accepts -c, -m, --json, -o, --skip-git-repo-check and - for stdin. It has no -C and no -s, and it runs in the process cwd, not the thread's original cwd. So the bridge spawns it in the original cwd (read from the rollout file) and keeps the sandbox with -c sandbox_mode="…".
• Fast mode: -c service_tier="fast" is accepted and recorded as service_tier: "priority". An unsupported tier produces an error item ("…not advertised as supported for model…"), which lands in warnings.
• Reasoning effort key: model_reasoning_effort. Supported levels come from Codex's own model list (<CODEX_HOME>/models_cache.json); at the time of writing the models offered low, medium, high, xhigh, max and most also ultra, and none offered minimal. Before starting Codex, the bridge checks effort against the effective model: the model input, else the thread's model for follow-ups, else the configured default. An unsupported level is rejected with the supported list. Unknown models are passed through unchecked. Verified live: low, xhigh, max and ultra are each recorded as the turn's reasoning_effort.
• Subagents (multi_agent, stable) work under exec: the child thread has thread_source: "subagent" and the parent's parent_thread_id.

Known limitations

• Occasionally a run sits for several minutes waiting on the model API (seen: 225 s and ~438 s for a one-word reply, both with and without fast mode; the next identical runs took ~7 s). The default 900 s timeout covers it.
• Settings this Codex version doesn't recognise produce a warning on every run until they're removed from ~/.codex/config.toml.
• On Windows, if codex.exe itself crashes while a grandchild still holds its pipes, that grandchild can outlive it (Node can't put children in a Job Object). Timeouts, cancellation and shutdown kill the whole tree.
• The thread lock is a lockfile with a 30 s heartbeat. A crashed holder is reclaimed after its PID is gone, or after 2 minutes without a heartbeat.
• macOS/Linux paths are implemented but untested.

Development

npm test          # build + node:test (unit tests use temp dirs and a fake codex)
node dist/index.js --doctor

Layout: src/index.ts (MCP tools), runner.ts (spawn, JSONL parsing, timeout and tree kill), codexPath.ts, lock.ts, configSync.ts, sandboxMirror.ts, home.ts, sessions.ts, util.ts.