Log inSubmit server
Codex Control Plane MCP logo

Codex Control Plane MCP

by aresyn

Durable MCP control plane for asynchronously running, monitoring, approving, and recovering Codex Desktop tasks.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Codex Control Plane MCP

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "aresyn-codex-control-plane-mcp": {
      "command": "uvx",
      "args": [
        "codex-control-plane-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Automated check passed— started and listed 38 tools correctly (1mo ago).

Overview

The aresyn/codex-control-plane-mcp MCP server turns Codex Desktop and codex-app-server into a durable, local worker for long-running tasks. It queues operations, returns an operationId or workflowId immediately, and exposes polling tools for progress, approvals, retries, diagnostics, and final reports. Plan Mode, code review, thread lifecycle actions, pending interactions, and SQLite-backed history are available through MCP tools. Reach for it when an orchestrator needs Codex Desktop work to survive client timeouts or MCP restarts without creating duplicate turns.

Use cases

  • Queue long-running Codex tasks without holding an MCP call open
  • Poll Plan Mode workflows and approve ready plans
  • Recover task context from chats, transcripts, and hook history
  • Inspect worker queues and resource-lock contention
  • Answer pending Codex approvals or interaction requests

Key features

  • Durable asynchronous operations with retry-safe request IDs
  • Plan Mode and code review workflows
  • SQLite-backed history and diagnostics
  • Worker, queue, and concurrency status inspection
  • Pending interaction and turn interruption controls
  • Thread archive, unarchive, and compaction actions

Tools38

What Codex Control Plane MCP lets your agent do. Expand a tool for its parameters.

Verified live~9.1k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

9/9 checks healthy over the last 78d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · codex-control-plane-mcp (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars124Stargazers on the source repository.
Last commit1mo agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed38Callable tools this server registers over MCP.
Directory activity5 viewsConfig copies, upvotes, and views on AllMCPs.

How Codex Control Plane MCP works

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 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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Codex Control Plane MCP

Install it with pipx or run it directly with uvx: `pipx install codex-control-plane-mcp` or `uvx codex-control-plane-mcp`.

The README provides Claude Desktop configuration examples and uses the server's stdio command, `codex-control-plane-mcp`.

Submit work asynchronously, receive an operationId or workflowId, and poll the corresponding status tool until completion.

Yes. Set `CODEX_MCP_EXECUTION_MODE=worker` for the worker process and use client mode for MCP clients that delegate queued operations.

Related MCP servers

All in Coding Agents All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewCodex Control Plane MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/aresyn-codex-control-plane-mcp?style=directory)](https://allmcps.com/mcp/aresyn-codex-control-plane-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/aresyn-codex-control-plane-mcp"><img src="https://allmcps.com/api/badge/aresyn-codex-control-plane-mcp?style=directory" alt="Codex Control Plane MCP on AllMCPs" /></a>