Codex Control Plane MCP

Codex Control Plane MCP

English | Русский

Reliable Codex Desktop automation for long tasks.

codex-control-plane-mcp turns Codex Desktop and codex-app-server into a durable worker that an MCP client can drive safely. Send a task, get an operationId or workflowId right away, poll until the work finishes, approve Plan Mode when needed, then read the final report.

The server handles the awkward parts that thin wrappers usually leave to the caller: app-server startup, thread and turn creation, retry safety, duplicate prompt protection, Plan Mode, approvals, local history, diagnostics, and repair.

OpenClaw and Hermes are first-class clients, but the server is useful for any local orchestrator that needs Codex Desktop to do long-running work without holding one MCP call open for hours.

The short version

MCP client / orchestrator

-> submit a task or start a Plan Mode workflow <- receive operationId or workflowId immediately -> poll status -> answer approvals or approve the plan <- read final report, diagnostics, threadId, and turnId

That gives you a simple contract:

• no multi-hour MCP calls;
• no duplicate Codex turns after a client retry;
• no blind fire-and-forget task submission;
• a local SQLite record of operations, workflows, turns, hooks, and diagnostics.

Why not just call Codex directly?

For a more detailed decision guide, see docs/THIN_WRAPPERS.md.

Current support

• Full live target: Windows with Codex Desktop and codex-app-server.
• Linux and macOS: protocol-only checks for now.
• Local-first: not intended to be exposed as a public network service.

Security model

This is a local-first control plane for trusted Codex Desktop environments.

Do not expose it as a network service without authentication.

Recommended first-run posture:

• use read-only for untrusted repositories;
• use on-request approval when testing new workflows;
• Plan Mode never runs with a read-only sandbox. If a caller requests read-only, MCP raises that turn to workspace-write and reports the adjustment in status output;
• keep state/, logs/, .env, and .codex/ private.

What it does

• Durable async queue for Codex write operations.
• Retry-safe client_request_id handling.
• Active duplicate prompt detection.
• SQLite leases and heartbeats for competing MCP processes.
• Recovery after MCP restart during thread/start or turn/start.
• Durable turn/steer for adding context to an active turn without creating a second turn.
• Durable thread/fork for branching an existing thread, with or without an initial message.
• Plan Mode workflows: start plan, poll, approve, execute, read final report.
• Plan Mode runtime floor: workspace-write, with runtimePolicyAdjusted in status when MCP raises a read-only request.
• Code review workflows through app-server review/start, with polling and final report capture.
• Structured final reports with output_schema.
• Thread lifecycle tools for archive, unarchive, and pollable compaction.
• Workflow goal sync with Codex Desktop thread goals.
• Image and local image inputs for turns that start through turn/start.
• Pending approvals and questions exposed as pollable MCP state.
• Turn interrupts by threadId/turnId, operationId, or workflowId.
• Runtime inventory for models, permission profiles, sandbox readiness, hooks, skills, provider features, account status, usage bands, rate-limit state, and supported app-server methods.
• Health checks, diagnostics, issue analysis, and dry-run repairs.
• MCP-owned hook history in SQLite for search, summaries, and fallback reads.
• Redacted app-server progress journal for deltas, warnings, model reroutes, and token usage.
• Structured MCP errors that automation code can branch on.

Write and control actions go through codex-app-server. The server does not mutate Codex internal SQLite databases or transcript files.

Install

Recommended:

pipx install codex-control-plane-mcp

Or run directly:

uvx codex-control-plane-mcp

From GitHub:

python -m pip install "codex-control-plane-mcp @ git+https://github.com/aresyn/codex-control-plane-mcp.git"

For local development:

git clone https://github.com/aresyn/codex-control-plane-mcp.git

cd codex-control-plane-mcp py -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -e ".[dev]" python -m pytest -q

MCP client config

After installation, generate a config:

codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects

Minimal stdio entry:

{

"mcpServers": { "codex-control-plane": { "command": "codex-control-plane-mcp", "args": [] } } }

More copy-paste examples for Claude Desktop, Cursor, VS Code-style MCP clients, local checkouts, installed packages, and central worker mode are available in examples/mcp-client-configs.md.

Run the MCP stdio server:

codex-control-plane-mcp

Or run it as a module:

py -m codex_control_plane_mcp.server

The old openclaw-codex-mcp and openclaw-codex-mcp-hooks commands remain as compatibility aliases for one release line.

Central worker mode

The default inline mode is still the simplest setup: one MCP process can submit and execute operations. For OpenClaw, Hermes, or any setup with several MCP clients, use a central worker instead.

Recommended local shape:

• every MCP client uses the same CODEX_HOME and CODEX_MCP_STATE_DB;
• OpenClaw gateway entries run with CODEX_MCP_EXECUTION_MODE=client;
• one long-running codex-control-plane-mcp-worker process owns codex-app-server, leases, queue slots, and resource locks;
• clients call codex_submit_task, then poll status. They do not execute queued operations themselves.

Worker command:

$env:CODEX_MCP_EXECUTION_MODE = "worker"

codex-control-plane-mcp-worker

Safe observation mode, useful before switching a live gateway:

codex-control-plane-mcp-worker --observe

Concurrency defaults:

CODEX_MCP_MAX_ACTIVE_TURNS_GLOBAL=4

CODEX_MCP_MAX_ACTIVE_TURNS_PER_PROJECT=3 CODEX_MCP_MAX_ACTIVE_TURNS_PER_AGENT=3 CODEX_MCP_MAX_ACTIVE_TURNS_PER_THREAD=1 CODEX_MCP_MAX_ACTIVE_WRITE_TURNS_PER_PROJECT=1 CODEX_MCP_MAX_APP_SERVER_PENDING_REQUESTS=8

For write turns in the same project, pass resource_keys to codex_submit_task. Without them, workspace-write and danger-full-access turns take a broad project write lock. With disjoint keys, the worker may run several write turns in parallel.

New status tools:

• codex_get_worker_status
• codex_get_queue_status
• codex_get_concurrency_status
• codex_get_worker_command_status

codex_get_operation_status also returns queueState, workerState, slotState, and resourceLockState. A running turn has slotState.claimed=true and a slotClaim with the worker id, slot type, and claim time. codex_get_queue_status separates queued work from running turn operations, auxiliary operations, active turn slots, and lock conflicts.

When a workflow is waiting for capacity, codex_get_workflow_status mirrors the nested operation queue state in workflowOperationQueueState. Use nextRecommendedAction="wait_for_worker_slot" for slot pressure and nextRecommendedAction="wait_for_resource_lock" for write lock conflicts. Do not create another operation for the same work while either action is returned.

First setup

The admin helper can generate a fuller client config, install hooks, and run a protocol smoke:

codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects

The command prints a JSON block you can copy into an MCP client config. It does not print secrets or private prompts.

You can also install only the Codex hooks:

codex-control-plane-mcp-hooks install --state-db .\state\codex-mcp-state.sqlite3

codex-control-plane-mcp-hooks status codex-control-plane-mcp-hooks doctor

The installer backs up ~/.codex/hooks.json, merges its handlers with your existing hooks, stores stateDb as an absolute path, and writes prompts, visible agent progress text, final answers, and turn status into the MCP state DB. Tool calls and command outputs are not recorded by default. Restart Codex after installing or changing hooks.

For turns launched through codex-app-server, the server mirrors the accepted prompt, visible assistant messages, and turn status into the same SQLite history. That keeps search and status reads useful even when app-server does not execute user hooks itself.

Main workflows

Submit a durable task:

codex_submit_task

-> operationId codex_get_operation_status(operationId) -> queued / running / waiting_for_approval / completed / failed

Use the same client_request_id when a caller retries after a transport timeout. The retry returns the existing operation instead of creating another turn.

Attach screenshots or other image evidence:

codex_submit_task(

operation_type="start_chat", message="Analyze this screen.", input_items=[ {"type": "localImage", "path": ".\\screens\\error.png", "detail": "low"}, {"type": "image", "url": "https://example.com/screenshot.png", "detail": "high"} ] )

Image inputs are accepted only for operation types that start a new turn: start_chat, send_message, execute_plan, and fork_thread with an initial message. MCP sends the path or URL to codex-app-server, but operation status and diagnostics return only safe metadata such as type, detail, size, extension, and hashes. Binary image content, raw URLs, and full local image paths are not stored in public status payloads.

Steer an active turn:

codex_submit_task(operation_type="steer_turn", thread_id=..., expected_turn_id=..., message=...)

-> operationId codex_get_operation_status(operationId) -> follows the target turn until completed / failed / interrupted

Use steer_turn only while the target turn is active. For a completed thread, use send_message instead.

Fork a thread:

codex_submit_task(operation_type="fork_thread", source_thread_id=...)

-> operationId codex_get_operation_status(operationId) -> completed, threadId=

Start work in the fork righ