codex-mcp-bridge

MCP server that wraps Codex CLI as a subprocess, exposing code execution, web search, and structured output as Model Context Protocol tools.

Works with any MCP client: Claude Code, Gemini CLI, Cursor, Windsurf, VS Code, or any tool that speaks MCP.

Do you need this?

If you're in a terminal agent (Claude Code, Codex CLI, Gemini CLI) with shell access, call Codex CLI directly. It's faster, cheaper, and zero overhead:

# Review current branch vs main
codex review --base main

# Review uncommitted changes
codex review --uncommitted

# Review with custom focus
codex review --base main "Focus on security and error handling"

# From a worktree (run inside the worktree; `-C` is broken for `review`)
cd /path/to/worktree && codex review --base main

# General analysis
codex exec "Analyze src/utils/parse.ts for edge cases"

Use this MCP bridge instead when:

• Your client has no shell access (Cursor, Windsurf, Claude Desktop, VS Code)

• You need structured output with JSON Schema validation (Codex CLI's --json has known bugs)

• You need partial response capture on timeout and automatic model fallback on quota exhaustion

• You want subprocess isolation: explicit env allowlist, no shell escape, secret redaction on output, FIFO-queued concurrency (max 3 parallel spawns, configurable via CODEX_MAX_CONCURRENT)

• You need multi-turn conversations via session resume (sessionId / resetSession, inspected via listSessions)

Worktree note: Codex CLI issue #9084 breaks codex -C /path review .... Run codex review from inside the worktree to avoid it.

Related MCP server: gemini-mcp-bridge

Quick Start

npx codex-mcp-bridge

Prerequisites

• Codex CLI installed (npm i -g @openai/codex)

• OPENAI_API_KEY environment variable set, or codex auth login completed

Claude Code

claude mcp add codex-bridge -- npx -y codex-mcp-bridge

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "npx",
      "args": ["-y", "codex-mcp-bridge"]
    }
  }
}

Cursor / Windsurf / VS Code

Add to your MCP settings:

{
  "codex-bridge": {
    "command": "npx",
    "args": ["-y", "codex-mcp-bridge"],
    "env": {
      "OPENAI_API_KEY": "sk-..."
    }
  }
}

Tools

codex

General-purpose execution. Supports multi-turn conversations via sessionId, sandbox levels (read-only, workspace-write, full-auto), and reasoning effort control. Pass resetSession: true to discard and start fresh. Use listSessions to inspect active sessions before resuming.

Key parameters: prompt (required), files, model, sessionId, sandbox, reasoningEffort, workingDirectory, timeout (default 60s).

search

Web search powered by OpenAI's native search infrastructure via Codex CLI's --search flag. Returns synthesized answers with source URLs.

Key parameters: query (required), model, workingDirectory, timeout (default 120s).

query

Lightweight, non-agentic text analysis. Spawns in an isolated temp directory so the bridge's repo context doesn't leak. Pass text to analyze in the context parameter. Supports reasoningEffort and maxResponseLength.

Key parameters: prompt (required), context, model, reasoningEffort, timeout (default 60s).

review

Thin wrapper around Codex CLI's native diff-aware review. The bridge passes the diff selector to codex exec review --json; upstream Codex owns the review prompt. Requires a real git repository via workingDirectory.

Key parameters: mode (required: uncommitted, base, or commit), workingDirectory (required), base (required for base mode), commit (required for commit mode), title, model, timeout (default 180s).

structured

Embeds a JSON Schema in the prompt and validates the response with Ajv. Returns clean JSON on success, validation errors on failure.

Key parameters: prompt (required), schema (required, JSON string), files, model, workingDirectory, timeout (default 60s).

ping

No parameters. Returns CLI version, auth status, model configuration, and concurrency diagnostics (activeCount, queueDepth).

mcpStatus

Reports per-server MCP state as Codex's own app-server protocol sees it. Unlike every other tool, it deliberately does not suppress Codex's MCP servers or harden the subprocess environment, because both would disable the thing being measured. It therefore boots the servers in ~/.codex/config.toml and is slower than a normal call. With diagnostics: true and a workingDirectory inside a trusted project, the thread it starts also boots that project's .codex/config.toml servers.

Key parameters: diagnostics (default false), workingDirectory, timeout (per-request, default 90s).

Reading the output:

• unknown is not a failure. It means the inventory carried no server info and no explicit verdict was available. Only diagnostics: true can report failed.

• A degraded warning means don't trust unknown. Slow calls have been observed reporting healthy servers as uninitialized, so the tool reports how long the underlying call took and flags the result when it was slow enough to be suspect.

• builtIn marks a server Codex injects that is not in your config; configuredButUnreported marks one in your config that Codex never mentioned.

Example:

atlassian            failed       auth=oAuth  tools=0
    error: MCP client for `atlassian` failed to start: MCP startup failed: failed to
    refresh OAuth tokens for server atlassian: ... invalid_grant: Grant not found
codex_apps           initialized  auth=bearerToken  tools=117  (builtIn)
linear               initialized  auth=oAuth  tools=57
serena               initialized  auth=unsupported  tools=22

All tools attach execution metadata (_meta) with durationMs, model, fallbackUsed, and session info where applicable. See DESIGN.md for details.

Code review with this CLI

This bridge does not bundle reviewer prompts. There are three paths for code review:

Native upstream codex review

codex review --base main
codex review --uncommitted
codex review --base main "Focus on security and error handling"

Diff-aware review built into Codex CLI. No bridge involvement. Use this when your client has shell access.

Bridge review tool for native diff-aware review

{
  "tool": "review",
  "arguments": {
    "mode": "base",
    "base": "main",
    "workingDirectory": "/path/to/worktree"
  }
}

The bridge runs codex exec review --json from workingDirectory, captures the final review text, and returns review metadata such as threadId, event counts, and redacted command output. It does not accept a prompt.

Bridge codex tool with caller-supplied prompt

{
  "tool": "codex",
  "arguments": {
    "prompt": "<your review prompt + diff or file references>",
    "sandbox": "read-only"
  }
}

The bridge runs codex exec --sandbox read-only with the supplied prompt and returns stdout. Use this for free-form review prompts or review inputs that are not expressible as uncommitted, base, or commit diff selectors.

Representative review prompt

A starting point; adapt freely:

Review the following diff:

<diff content>

Look for:
- Bugs that would surface in production
- Missing error handling on user-supplied input
- Tests modified to silence failures rather than verify behaviour
- Security issues (injection, missing auth checks, secret leaks)

For each finding cite file:line, severity (high/medium/low), and a suggested fix.
Skip style/formatting; assume an autoformatter handles those.

The bridge has no opinion on prompt content. See ADR-001 for the rationale.

Configuration

Running the bridge against a second Codex account

CODEX_HOME is a complete identity switch: auth, config.toml, skills and thread history all live under the root, so a second root is a second install. Every tool call this bridge makes is machine traffic rather than a session someone is sitting in front of, which makes it a good candidate for a work or team seat while interactive codex keeps a personal one.

Set it in the server registration rather than the ambient shell, so the choice does not depend on which terminal launched the client:

{
  "mcpServers": {
    "codex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codex-mcp-bridge"],
      "env": {
        "CODEX_HOME": "/home/you/.codex-work",
        "CODEX_DEFAULT_MODEL": "gpt-5.6-sol"
      }
    }
  }
}

Three things to know before you do:

• Log in as that root first, since a root is only as usable as its credentials: CODEX_HOME=/home/you/.codex-work codex login (or codex login --with-api-key). Check it with CODEX_HOME=/home/you/.codex-work codex login status.

• A JSON env block has no conditional. If that root loses its login, every subprocess the bridge spawns targets it anyway, with no fallback to the default root the way a shell wrapper could offer one.

• Set CODEX_DEFAULT_MODEL alongside it. The bridge resolves config.toml from CODEX_HOME, so a freshly created root has none and the model drops to the CLI default. That absence also makes most of CODEX_MCP_SERVERS inert: with nothing configured there is nothing to disable, nothing to inherit and no name to enable, which is what the default setting wants anyway. The one mode it does not disarm is a raw TOML override (a value starting { or [), which is passed straight through as -c mcp_servers=... and never reads config.toml.

Choosing a Codex MCP server

Performance

Codex CLI has minimal startup overhead (<100ms), so wall time is dominated by model inference.

Default timeouts (60-300s) are comfortable for typical workloads.

Bridge family

Two MCP servers, same architecture, different underlying CLIs. Each wraps a terminal agent as a subprocess and exposes it as MCP tools. Pick the one that matches your model provider, or run both for cross-model workflows.

Both share: subprocess env isolation, path sandboxing, output redaction (secret stripping), FIFO concurrency queue, MCP tool annotations, _meta response metadata, progress heartbeats.

Development

npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm test             # Run tests
npm run lint         # ESLint
npm run typecheck    # tsc --noEmit

Further reading

• DESIGN.md - Architecture, MCP server control grammar, sessions, output parsing, response metadata

• SECURITY.md - Environment isolation, path sandboxing, output redaction, resource limits

• CHANGELOG.md - Release history

License

MIT