Codex Control Plane MCP

What aresyn/codex-control-plane-mcp MCP server does

The aresyn/codex-control-plane-mcp MCP server provides an asynchronous control layer around Codex Desktop and codex-app-server. Instead of keeping one MCP request open for the duration of a long task, a client submits work and receives an operationId or workflowId. It can then poll persisted state until the operation reaches a terminal result.

The server covers project discovery, chat and transcript lookup, task submission, Plan Mode, code review workflows, approvals, interaction requests, turn interruption, thread archiving, unarchiving, and context compaction. It also records operations, workflows, turns, hooks, and diagnostics in a local SQLite database. Hook history supports search, summaries, and fallback reads.

How it works

A typical flow begins with codex_list_projects, followed by codex_preflight_project_run for a specific project. The client submits a durable operation with codex_submit_task, including a client_request_id, and polls codex_get_operation_status. Status responses provide queue and worker guidance so the caller can wait instead of creating an unsafe retry.

Plan-based work follows a separate workflow: start it with codex_start_plan_workflow, poll codex_get_workflow_status, approve a ready plan with codex_approve_plan, and continue polling for execution and the final report. Review workflows use the same durable polling pattern. Pending approvals or questions can be found with codex_list_pending_interactions and answered with codex_answer_pending_interaction.

The aresyn/codex-control-plane-mcp MCP server can run in inline mode, where one MCP process submits and executes operations, or in client mode with a separate central worker. The worker owns app-server execution, leases, queue slots, and resource locks. Queue, concurrency, worker, and delegated command status tools help diagnose capacity and lifecycle issues.

Setup and configuration

The project requires Python 3.11 or newer. The README documents installation with pipx install codex-control-plane-mcp, direct execution with uvx codex-control-plane-mcp, or installation from the GitHub repository. The MCP stdio command is codex-control-plane-mcp; it can also be run as py -m codex_control_plane_mcp.server.

An administrative command can initialize configuration with a state database and projects root. A minimal MCP client entry uses the stdio command with no arguments. Central worker deployments use one long-running codex-control-plane-mcp-worker process and set CODEX_MCP_EXECUTION_MODE=worker; client processes use client. Shared CODEX_HOME and CODEX_MCP_STATE_DB are recommended when multiple clients use the same worker.

Tools and capabilities

The aresyn/codex-control-plane-mcp MCP server exposes tools for:

• Discovering projects, chats, active chats, and searchable history.
• Starting, submitting, steering, interrupting, and inspecting Codex work.
• Running Plan Mode and review workflows with persisted state.
• Approving plans and answering pending approvals or questions.
• Inspecting workers, queues, concurrency, turns, and delegated commands.
• Archiving threads, restoring them, and starting or polling compaction.
• Reading diagnostics, health information, runtime inventory, and final reports.

Write and control actions are sent through codex-app-server. The server does not directly modify Codex internal SQLite databases or transcript files.

Limitations and notes

The fully supported live target is Windows with Codex Desktop and codex-app-server. Linux and macOS currently receive protocol-only checks. The project is local-first and is not intended to be exposed as a public network service.

The README recommends read-only for untrusted repositories and on-request approval while testing. Plan Mode requires at least workspace-write; a requested read-only setting is raised and reported in status output. Keep the state directory, logs, .env, and .codex data private, and do not expose the service remotely without authentication.

Plan Mode, execution, and other operations should be polled using the returned identifiers. Search results are for discovery and recovery, not proof that a turn remains active, and row age alone should not be used to infer a stalled turn.