# mcp-codex-dev
MCP Server for integrating [Codex CLI](https://github.com/openai/codex) into Claude Code workflows with session management and real-time progress monitoring.
<img width="1890" height="948" alt="image" src="https://github.com/user-attachments/assets/490a8cf6-1267-42cd-8f6f-e0a82c0dc6a3" />
## Installation
Prerequisites: [Codex CLI](https://github.com/openai/codex) installed and configured.
In .mcp.json file
```
{
"mcpServers": {
"mcp-codex-dev": {
"command": "npx",
"args": ["-y", "mcp-codex-dev"]
}
}
}
```
or
```bash
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
```powershell
claude mcp add mcp-codex-dev -- cmd /c npx -y mcp-codex-dev
```
## Tools
| Tool | Description |
|------|-------------|
|`exec`|Clean dialogue without templates, supports session resume|
| `write` | Write code via Codex CLI, supports session resume |
|`tdd`|write tool 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`:
```json
{
"model": "gpt-5.2",
"sandbox": "danger-full-access",
"timeout": 300000,
"tools": {
"write": { "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.
