{
  "markdown": "# codex-mcp-bridge\n\n[![npm version](https://img.shields.io/npm/v/codex-mcp-bridge)](https://www.npmjs.com/package/codex-mcp-bridge)\n[![npm downloads](https://img.shields.io/npm/dm/codex-mcp-bridge)](https://www.npmjs.com/package/codex-mcp-bridge)\n[![CI](https://github.com/hampsterx/codex-mcp-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/hampsterx/codex-mcp-bridge/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/node/v/codex-mcp-bridge)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2)](https://modelcontextprotocol.io/)\n\nMCP server that wraps [Codex CLI](https://github.com/openai/codex) as a subprocess, exposing code execution, web search, and structured output as [Model Context Protocol](https://modelcontextprotocol.io/) tools.\n\nWorks with any MCP client: Claude Code, Gemini CLI, Cursor, Windsurf, VS Code, or any tool that speaks MCP.\n\n## Do you need this?\n\nIf 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:\n\n```bash\n# Review current branch vs main\ncodex review --base main\n\n# Review uncommitted changes\ncodex review --uncommitted\n\n# Review with custom focus\ncodex review --base main \"Focus on security and error handling\"\n\n# From a worktree (run inside the worktree; `-C` is broken for `review`)\ncd /path/to/worktree && codex review --base main\n\n# General analysis\ncodex exec \"Analyze src/utils/parse.ts for edge cases\"\n```\n\n**Use this MCP bridge instead when:**\n- Your client has no shell access (Cursor, Windsurf, Claude Desktop, VS Code)\n- You need structured output with JSON Schema validation (Codex CLI's `--json` has [known bugs](https://github.com/openai/codex/issues/16552))\n- You need partial response capture on timeout and automatic model fallback on\n  quota exhaustion\n- You want subprocess isolation: explicit env allowlist, no shell escape,\n  secret redaction on output, FIFO-queued concurrency (max 3 parallel spawns,\n  configurable via `CODEX_MAX_CONCURRENT`)\n- You need multi-turn conversations via session resume (`sessionId` /\n  `resetSession`, inspected via `listSessions`)\n\nWorktree note: Codex CLI issue [#9084](https://github.com/openai/codex/issues/9084)\nbreaks `codex -C /path review ...`. Run `codex review` from inside the worktree to avoid it.\n\n## Quick Start\n\n```bash\nnpx codex-mcp-bridge\n```\n\n### Prerequisites\n\n- [Codex CLI](https://github.com/openai/codex) installed (`npm i -g @openai/codex`)\n- `OPENAI_API_KEY` environment variable set, or `codex auth login` completed\n\n### Claude Code\n\n```bash\nclaude mcp add codex-bridge -- npx -y codex-mcp-bridge\n```\n\n### Gemini CLI\n\nAdd to `~/.gemini/settings.json`:\n```json\n{\n  \"mcpServers\": {\n    \"codex-bridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"codex-mcp-bridge\"]\n    }\n  }\n}\n```\n\n### Cursor / Windsurf / VS Code\n\nAdd to your MCP settings:\n```json\n{\n  \"codex-bridge\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"codex-mcp-bridge\"],\n    \"env\": {\n      \"OPENAI_API_KEY\": \"sk-...\"\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| **codex** | Execute prompts with file context, session resume, and sandbox control. Multi-turn conversations via session IDs. Use for free-form review prompts; see [Code review with this CLI](#code-review-with-this-cli). |\n| **review** | Native diff-aware Codex review via `codex exec review --json`. No caller prompt; supports uncommitted, base branch, and commit review modes. |\n| **search** | Web search via `codex --search`. Returns synthesized answers with source URLs. |\n| **query** | Lightweight text analysis. No repo context, no sessions. Runs in an isolated temp directory. |\n| **structured** | JSON Schema validated output via [Ajv](https://ajv.js.org/). Data extraction, classification, or any task needing machine-parseable output. |\n| **ping** | Health check with CLI version, capabilities, and concurrency diagnostics (`activeCount`, `queueDepth`). |\n| **mcpStatus** | Report what Codex says about each MCP server it knows about: auth type, tool inventory, and whether it initialized. Optional diagnostic mode adds explicit failure states and error text. |\n| **listSessions** | List active conversation sessions with metadata (turn count, model, timestamps). |\n\n### codex\n\nGeneral-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.\n\nKey parameters: `prompt` (required), `files`, `model`, `sessionId`, `sandbox`, `reasoningEffort`, `workingDirectory`, `timeout` (default 60s).\n\n### search\n\nWeb search powered by OpenAI's native search infrastructure via Codex CLI's `--search` flag. Returns synthesized answers with source URLs.\n\nKey parameters: `query` (required), `model`, `workingDirectory`, `timeout` (default 120s).\n\n### query\n\nLightweight, 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`.\n\nKey parameters: `prompt` (required), `context`, `model`, `reasoningEffort`, `timeout` (default 60s).\n\n### review\n\nThin 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`.\n\nKey parameters: `mode` (required: `uncommitted`, `base`, or `commit`), `workingDirectory` (required), `base` (required for `base` mode), `commit` (required for `commit` mode), `title`, `model`, `timeout` (default 180s).\n\n### structured\n\nEmbeds a JSON Schema in the prompt and validates the response with Ajv. Returns clean JSON on success, validation errors on failure.\n\nKey parameters: `prompt` (required), `schema` (required, JSON string), `files`, `model`, `workingDirectory`, `timeout` (default 60s).\n\n### ping\n\nNo parameters. Returns CLI version, auth status, model configuration, and concurrency diagnostics (`activeCount`, `queueDepth`).\n\n### mcpStatus\n\nReports 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.\n\nKey parameters: `diagnostics` (default `false`), `workingDirectory`, `timeout` (per-request, default 90s).\n\n| Mode | Cost | What you get |\n|------|------|--------------|\n| default | ~6-9s | Inventory: auth type, tool names and counts, and `initialized` / `unknown` per server. Creates no thread and writes no session record. |\n| `diagnostics: true` | ~10-20s | Adds an explicit `failed` state and the error text naming the cause (expired OAuth grant, missing binary, remote refusal). Starts an ephemeral thread, which is never materialised on disk. |\n\nReading the output:\n\n- **`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`.\n- **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.\n- **`builtIn`** marks a server Codex injects that is not in your config; **`configuredButUnreported`** marks one in your config that Codex never mentioned.\n\nExample:\n\n```text\natlassian            failed       auth=oAuth  tools=0\n    error: MCP client for `atlassian` failed to start: MCP startup failed: failed to\n    refresh OAuth tokens for server atlassian: ... invalid_grant: Grant not found\ncodex_apps           initialized  auth=bearerToken  tools=117  (builtIn)\nlinear               initialized  auth=oAuth  tools=57\nserena               initialized  auth=unsupported  tools=22\n```\n\nAll tools attach execution metadata (`_meta`) with `durationMs`, `model`, `fallbackUsed`, and session info where applicable. See [DESIGN.md](DESIGN.md) for details.\n\n## Code review with this CLI\n\nThis bridge does not bundle reviewer prompts. There are three paths for code review:\n\n### Native upstream `codex review`\n\n```bash\ncodex review --base main\ncodex review --uncommitted\ncodex review --base main \"Focus on security and error handling\"\n```\n\nDiff-aware review built into Codex CLI. No bridge involvement. Use this when your client has shell access.\n\n### Bridge `review` tool for native diff-aware review\n\n```jsonc\n{\n  \"tool\": \"review\",\n  \"arguments\": {\n    \"mode\": \"base\",\n    \"base\": \"main\",\n    \"workingDirectory\": \"/path/to/worktree\"\n  }\n}\n```\n\nThe 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.\n\n### Bridge `codex` tool with caller-supplied prompt\n\n```jsonc\n{\n  \"tool\": \"codex\",\n  \"arguments\": {\n    \"prompt\": \"<your review prompt + diff or file references>\",\n    \"sandbox\": \"read-only\"\n  }\n}\n```\n\nThe 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.\n\n### Representative review prompt\n\nA starting point; adapt freely:\n\n```text\nReview the following diff:\n\n<diff content>\n\nLook for:\n- Bugs that would surface in production\n- Missing error handling on user-supplied input\n- Tests modified to silence failures rather than verify behaviour\n- Security issues (injection, missing auth checks, secret leaks)\n\nFor each finding cite file:line, severity (high/medium/low), and a suggested fix.\nSkip style/formatting; assume an autoformatter handles those.\n```\n\nThe bridge has no opinion on prompt content. See [ADR-001](docs/decisions/001-remove-review-and-assess-tools.md) for the rationale.\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CODEX_DEFAULT_MODEL` | *(CLI default)* | Default model for all tools |\n| `CODEX_FALLBACK_MODEL` | `o3` | Fallback on quota exhaustion (`none` to disable) |\n| `CODEX_CLI_PATH` | `codex` | Path to CLI binary |\n| `CODEX_MAX_CONCURRENT` | `3` | Max concurrent subprocess spawns |\n| `CODEX_MCP_SERVERS` | *(unset)* | Control which Codex internal MCP servers stay enabled. See [DESIGN.md](DESIGN.md#codex-internal-mcp-server-control). |\n\n## Choosing a Codex MCP server\n\n| You need... | Consider |\n|-------------|----------|\n| Structured output, model fallback, concurrency management, session resume | This bridge |\n| Session threading with `conversationId`, callback URI forwarding | [@tuannvm/codex-mcp-server](https://github.com/tuannvm/codex-mcp-server) |\n| Structured patch output with approval policies | [cexll/codex-mcp-server](https://github.com/cexll/codex-mcp-server) |\n| Minimal `codex exec` wrapper with parallel subagents | [codex-as-mcp](https://github.com/kky42/codex-as-mcp) |\n| Native Codex MCP (experimental, no wrapper needed) | `codex mcp serve` ([docs](https://github.com/openai/codex)) |\n\n## Performance\n\nCodex CLI has minimal startup overhead (<100ms), so wall time is dominated by model inference.\n\n| Scenario | Typical time |\n|----------|-------------|\n| Trivial prompt | 9-12s |\n| Web search | ~17s |\n\nDefault timeouts (60-300s) are comfortable for typical workloads.\n\n## Bridge family\n\nTwo 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.\n\n| | [codex-mcp-bridge](https://github.com/hampsterx/codex-mcp-bridge) | [claude-mcp-bridge](https://github.com/hampsterx/claude-mcp-bridge) |\n|---|---|---|\n| **CLI** | Codex CLI | Claude Code |\n| **Provider** | OpenAI | Anthropic |\n| **Tools** | codex, review, search, query, structured, ping, listSessions | query, review, search, structured, ping, listSessions |\n| **Code review** | `review` tool wrapping native `codex exec review --json`, or `codex` tool with caller-supplied prompt | `review` tool with caller-supplied prompt and hardened isolation defaults |\n| **Structured output** | Ajv validation | Native `--json-schema` |\n| **Session resume** | Session IDs with multi-turn | Native `--resume` |\n| **Budget caps** | Not supported | Native `--max-budget-usd` |\n| **Effort control** | `reasoningEffort` (low/medium/high) | `--effort low/medium/high/max` |\n| **Cold start** | <100ms (inference dominates) | ~1-2s |\n| **Auth** | `OPENAI_API_KEY` | `claude login` (subscription) or `ANTHROPIC_API_KEY` |\n| **Cost** | Pay-per-token | Subscription (included) or API credits |\n| **Concurrency** | 3 (configurable) | 3 (configurable) |\n| **Model fallback** | Auto-retry with fallback model | Auto-retry with fallback model |\n\nBoth share: subprocess env isolation, path sandboxing, output redaction (secret stripping), FIFO concurrency queue, MCP tool annotations, `_meta` response metadata, progress heartbeats.\n\n## Development\n\n```bash\nnpm install\nnpm run build        # Compile TypeScript\nnpm run dev          # Watch mode\nnpm test             # Run tests\nnpm run lint         # ESLint\nnpm run typecheck    # tsc --noEmit\n```\n\n## Further reading\n\n- [DESIGN.md](DESIGN.md) - Architecture, MCP server control grammar, sessions, output parsing, response metadata\n- [SECURITY.md](SECURITY.md) - Environment isolation, path sandboxing, output redaction, resource limits\n- [CHANGELOG.md](CHANGELOG.md) - Release history\n\n## License\n\nMIT\n",
  "bytes": 14060,
  "sha": "702f862c772668c223e668dbe85e4fcb373e321ddc9959641ec79693a1f568cf",
  "repo_slug": "hampsterx/codex-mcp-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hampsterx_codex_mcp_bridge_64f06391/readme"
}