mcp-codex-dev

English | 中文

MCP Server for integrating Codex CLI into Claude Code workflows with session management and real-time progress monitoring.

Installation

Prerequisites: Codex CLI installed and configured.

In .mcp.json file

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

claude mcp add mcp-codex-dev -- npx -y mcp-codex-dev

Windows OS:

{
  "mcpServers": {
    "mcp-codex-dev": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-codex-dev"]
    }
  }
}

claude mcp add mcp-codex-dev -- cmd /c npx -y mcp-codex-dev

Tools

| Tool | Description | |------|-------------| |exec|Clean dialogue without templates, supports session resume| |tdd|Codex CLI with built-in test-driven development prompt template| | review | Code review (spec + quality in parallel), supports resume | | health | Environment and config diagnostics | | session_list | List tracked sessions | | session_discard | Discard sessions |

Configuration

Create ~/.mcp/mcp-codex-dev/config.json:

{
  "model": "gpt-5.2",
  "sandbox": "danger-full-access",
  "timeout": 300000,
  "tools": {
    "tdd": { "model": "gpt-5.3-codex", "sandbox": "danger-full-access", "timeout": 2000000},
    "review": { "model": "gpt-5.2", "sandbox": "danger-full-access", "timeout": 3000000},
    "health": { "enabled": false }
  }
}

Top-level model / sandbox / timeout are global defaults. The tools section overrides per tool (keyed by tool name). Set "enabled": false to disable a tool.

Per-project config can be placed at <project>/.mcp/mcp-codex-dev.config.json.

Progress Server

A local HTTP server starts at http://localhost:23120 showing real-time progress. Configurable via progressPort.

When multiple MCP server instances run simultaneously, they share a single progress page: the first instance binds the port and serves the UI, and other instances forward their progress events to it.

Session Tracking

Session tracking metadata is stored per project at <project>/.mcp/mcp-codex-dev/sessions.json (where <project> is the Git repo root if applicable).

Codex CLI's own session files remain in ~/.codex/sessions/<id>/.

License

No license.

MCP Servers