mcp-codex-worker

A stdio MCP server that bridges MCP clients to the Codex app-server runtime. Provides 5 task tools for fully autonomous agent orchestration — spawn, wait, respond, message, cancel. All commands and file edits are auto-approved. Full observability via file-backed reporting and MCP resource subscriptions.

Does not call OpenAI APIs directly — all work is delegated to codex app-server (see codex-app-server protocol reference).

Install

npx -y mcp-codex-worker@latest

Add to Claude Code:

{
  "mcpServers": {
    "codex-worker": {
      "command": "npx",
      "args": ["-y", "mcp-codex-worker@latest"],
      "env": {
        "CODEX_LB_API_KEY": "${CODEX_LB_API_KEY}"
      }
    }
  }
}

Companion skill (optional)

npx -y skills add -y -g yigitkonur/skills-by-yigitkonur/skills/run-codex-subagents

Requirements

• Node 22+
• codex CLI installed
• CODEX_LB_API_KEY or OPENAI_API_KEY in environment

Tools

| Tool | Purpose | |---|---| | spawn-task | Create and start a task. Returns task_id, disk_paths, and "what to do next" guidance. | | wait-task | Block until completion/failure/input. Returns output, liveness signals, and next actions. | | respond-task | Answer agent questions (user_input only — approvals are auto-handled). | | message-task | Send follow-up instructions to a running task. | | cancel-task | Cancel one or more tasks (single or batch). |

Model selection

Only gpt-5.4 — pass the reasoning parameter:

| Value | Use case | |---|---| | gpt-5.4(medium) | Default. Most coding, refactors, debugging. | | gpt-5.4(high) | Multi-file reasoning, subtle bugs, design decisions. | | gpt-5.4(xhigh) | Deep research, novel architecture. | | gpt-5.4(low) | Trivial mechanical edits. |

Typical workflow

spawn-task { prompt: "..." }
  → { task_id: "bold-eagle-456", status: "working", disk_paths: {...} }
    ---
    **What to do next:**
    - Call `wait-task` with task_id to block until done.
    - If you have more tasks, launch them now — all run in parallel.

wait-task { task_id: "bold-eagle-456" }
  → { status: "completed", output: [...] }
    ---
    **What to do next:**
    - Read `task:///bold-eagle-456` for the full result.

No respond-task needed for command/file approvals — they're auto-approved instantly.

Auto-Approval

The server auto-approves ALL Codex approval requests without waiting:

| Request | Response | Log | |---|---|---| | Command approval | accept | [auto-approve] cmd: npm test | | File change | accept | [auto-approve] file change | | MCP elicitation | accept | [auto-approve] elicitation | | Permission request | grant all for session | [auto-approve] permissions |

Only user_input (agent asks a question) and dynamic_tool (external tool needs data) still pause the task.

Combined with approval_policy = "never" and sandbox_mode = "danger-full-access" from your config.toml, agents run fully autonomously.

Reporting & Observability

Every task persists to ~/.mcp-codex-worker/tasks/<task-id>/:

| File | Content | |---|---| | meta.json | Task state snapshot (refreshes every 10s during activity) | | summary.log | Formatted one-liners: [HH:MM:SS] cmd: npm test (exit 0, 1.2s) | | verbose.log | Full execution trace, streaming command output | | events.jsonl | Raw Codex notification stream — every event with timestamp |

MCP Resources

| URI | Content | |---|---| | task:///all | Scoreboard (auto-subscribed, push on change) | | task:///{id} | Task detail with metadata | | task:///{id}/log | Summary log | | task:///{id}/log.verbose | Verbose log (reads from disk) | | task:///{id}/events | Raw event trace (JSONL from disk) |

Resource Subscriptions

{ "resources": { "subscribe": true, "listChanged": true } }

• task:///all auto-subscribed at startup
• notifications/resources/updated on status changes (immediate) and output (throttled 1s)
• notifications/resources/list_changed on task creation

Codex App-Server Integration

This server acts as a client to the Codex app-server protocol. Key integration points:

| Feature | How we use it | |---|---| | initialize | experimentalApi: true, then account/login/start with API key | | thread/start | Omit approvalPolicy/sandbox — config.toml takes effect | | turn/start | Pass effort for reasoning level | | Approval requests | Auto-respond via respondToServerRequest() | | turn/completed | Captures turn status in summary log | | item/* notifications | Event capture module processes 6 types into logs | | error notification | Captures codexErrorInfo classification | | stderr | Piped to verbose.log and events.jsonl for diagnostics | | Process exit | Detects exit code/signal, classifies auth errors |

Auth

On startup, sends account/login/start with CODEX_LB_API_KEY (or OPENAI_API_KEY) to switch from stale OAuth tokens to API key auth. This prevents the "refresh token already used" crash.

Crash Recovery

On restart, loads all meta.json files from disk. Terminal tasks restore as-is. Non-terminal tasks (RUNNING, WAITING_ANSWER) are marked UNKNOWN since Codex sessions don't survive restarts.

Wire States (SEP-1686)

| State | Meaning | |---|---| | submitted | Queued, not started | | working | Agent executing | | input_required | Paused — needs user_input or dynamic_tool response | | completed | Done | | failed | Error (includes AUTH_TOKEN_EXPIRED, RATE_LIMITED classifications) | | cancelled | Interrupted by user | | unknown | Crash recovery fallback |

Environment Variables

| Variable | Description | Default | |---|---|---| | CODEX_LB_API_KEY | API key for codex-lb provider | — | | OPENAI_API_KEY | Fallback API key | — | | CODEX_APP_SERVER_COMMAND | Codex binary path | codex | | CODEX_APP_SERVER_ARGS | App-server arguments | app-server --listen stdio:// | | CODEX_HOME_DIRS | Colon-separated profile roots for failover | ~/.codex | | CODEX_ENABLE_FLEET | Enable fleet mode (sub-agent instructions) | off |

Development

npm install
npm run build        # TypeScript compile
npm test             # 158 unit tests
npm run smoke        # live Codex test (needs CODEX_LB_API_KEY)
npm run serve        # start locally

Testing with mcpc

mcpc --config config.json cw connect @test
mcpc @test tools-list
mcpc @test resources-read "task:///all"
mcpc @test tools-call spawn-task '{"prompt":"echo hello","reasoning":"gpt-5.4(low)"}'

Use the local build (node --import tsx src/index.ts) for mcpc — npx has bridge startup timing issues.