codex-mcp-bridge

MCP server that wraps Codex CLI as a subprocess, exposing code execution, agentic review, 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
codex -C /path/to/worktree 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 want to know the cost before paying it: assess classifies a diff in <2s (no CLI spawn) and recommends a review depth with estimated wall time
• You need graduated review depth rather than all-or-nothing: scan (diff-only, 120s), focused (reads changed files, 120-300s), deep (full agentic, up to 30min) with per-depth auto-scaled timeouts. Focused containment is --sandbox read-only --skip-git-repo-check --ephemeral plus prompt guidance; Codex can still invoke shell commands, so it is lighter containment than Gemini plan mode
• 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)

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).

review

Two modes:

• Agentic (default): Codex runs in --full-auto inside the repo. It diffs, reads files, follows imports, checks tests, and reads project instruction files before reviewing. Timeout auto-scales from diff size.
• Quick (quick: true): Diff-only review, no repo exploration. Faster but less context.

Key parameters: uncommitted (default true), base, focus, quick, workingDirectory, timeout (default auto-scaled agentic, 120s quick).

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).

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).

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

Configuration

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

Three 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 multiple for cross-model workflows.

All three share: subprocess env isolation, path sandboxing, FIFO concurrency queue, MCP tool annotations, _meta response metadata, progress heartbeats. The codex and claude bridges also perform output redaction (secret stripping).

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