Integrate Codex CLI into Claude Code workflows with session management.
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"]
}
}
}
or
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"]
}
}
}
or
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 /.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 /.mcp/mcp-codex-dev/sessions.json (where `` is the Git repo root if applicable).
Codex CLI's own session files remain in ~/.codex/sessions/<id>/.
License
No license.
Tools (6)
execClean dialogue without templates, supports session resumetddCodex CLI with built-in test-driven development prompt templatereviewCode review (spec + quality in parallel), supports resumehealthEnvironment and config diagnosticssession_listList tracked sessionssession_discardDiscard sessionsEnvironment Variables
progressPortPort for the local HTTP progress monitoring serverConfiguration
{"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 }}}