# aresyn/codex-control-plane-mcp [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/aresyn/codex-control-plane-mcp  
**GitHub Stars:** 122  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/aresyn-codex-control-plane-mcp

## Description
Durable control plane for long-running Codex Desktop tasks. Submit tasks asynchronously, poll operation/workflow state, approve Plan Mode, recover retries, and use hook-backed SQLite history for search and diagnostics.

## Tools
Capabilities this server exposes over MCP:

- **codex_list_projects** — List known Codex projects from registry, hook history, transcripts, and cached Codex state. Use this before preflight or submit when you need a project reference; later tools accept projectId, project name, or project path and return canonical projectId. Next call codex_preflight_project_run for a concrete project.
- **codex_list_project_chats** — List chats for one project from the bounded read model. Use this to find existing threads before continuation or review. Next call codex_get_chat_status, codex_get_chat, or codex_submit_task.
- **codex_list_active_chats** — List chats that look active from tracked, hook, transcript, or cached evidence. Use this for operator inspection, not for creating retries. Next call codex_get_turn_status or codex_get_operation_status when ids are available.
- **codex_search_chats** — Search chat history through the MCP-owned index and safe fallback sources. Use this for discovery or recovery when ids were lost. Do not use search results as proof that a turn is still active.
- **codex_get_chat_status** — Read lightweight chat status and safe previews. Use this to inspect a known thread without starting live work. Next call codex_get_chat for content or codex_submit_task for a new operation.
- **codex_get_chat** — Read bounded chat content from hook history, transcripts, or legacy fallback. Use this for context recovery and final report inspection. It is not a write path and should not trigger retries.
- **codex_send_message** — Compatibility write for sending a message to an existing Codex thread. Prefer codex_submit_task with operation_type='send_message' for durable long work. In client mode this delegates to the durable queue.
- **codex_start_chat** — Compatibility write for starting a new Codex chat. Prefer codex_submit_task with operation_type='start_chat' for durable long work. In client mode this delegates to the durable queue.
- **codex_start_plan_workflow** — Start a durable Plan Mode workflow and return workflowId immediately. Use this when a plan must be prepared before implementation. Next poll codex_get_workflow_status, then call codex_approve_plan when latestPlan is ready.
- **codex_start_review_workflow** — Start a durable Codex review workflow and return workflowId immediately. Use this for code review tasks. Next poll codex_get_workflow_status for progress and final report.
- **codex_get_workflow_status** — Poll workflow state from storage by default. Use this for Plan Mode, execution, and review workflows. Follow nextRecommendedAction and do not create replacement work unless guidance tells you to.
- **codex_adopt_workflow_plan** — Adopt a valid newer Plan Mode candidate already present in the workflow thread. Use this only when status or diagnostics reports an adoptable plan. Next poll codex_get_workflow_status.
- **codex_approve_plan** — Approve the latest ready plan and queue execution. Use this after codex_get_workflow_status reports plan_ready and a valid latestPlan. Next poll codex_get_workflow_status with the same workflowId.
- **codex_preflight_project_run** — Check whether a project is safe to use before a Codex run. Use this after project discovery and before write operations. Do not treat skipped worker-managed account checks as hard auth failures.
- **codex_get_turn_status** — Read one tracked Codex turn, including safe progress and terminal evidence. Use this when you have threadId and turnId. Do not infer stalled state from row age alone.
- **codex_execute_plan** — Compatibility write for executing an approved plan. Prefer codex_approve_plan or codex_submit_task with operation_type='execute_plan'. In client mode this delegates to durable workflow execution.
- **codex_submit_task** — Queue a durable Codex write operation and return operationId immediately. For project-scoped work, pass project_id from codex_list_projects.projectId; project name or project path are accepted aliases and MCP stores the canonical projectId. Always pass client_request_id and poll codex_get_operation_status.
- **codex_get_operation_status** — Poll a durable operation from storage. Use this after codex_submit_task and follow nextRecommendedAction, pollRecommended, queueState, and agentGuidance. Never create a new retry while an existing operation is active.
- **codex_list_pending_interactions** — List pending approvals, input requests, or elicitation requests. Use this when operation or workflow status reports pending interaction. Next answer with codex_answer_pending_interaction or ask a human.
- **codex_answer_pending_interaction** — Answer one pending Codex interaction so a turn can continue. Use this only for a listed interaction id. Next poll the owning operation, turn, or workflow.
- **codex_interrupt_turn** — Interrupt a running Codex turn by direct ids or durable operation/workflow context. Use this for explicit cancellation or stop conditions. Next poll status until terminal evidence is visible.
- **codex_archive_thread** — Archive a known Codex thread through the worker or app-server command lane. Use this only when the thread has no active work. Next poll codex_get_worker_command_status when commandId is returned.
- **codex_unarchive_thread** — Unarchive a known Codex thread through the worker or app-server command lane. Use this only for an existing archived thread. Next poll codex_get_worker_command_status when commandId is returned.
- **codex_start_thread_compaction** — Start context compaction for a known thread and return actionId. Use this after active work is terminal. Next poll codex_get_thread_compaction_status.
- **codex_get_thread_compaction_status** — Poll a thread compaction action. Use this with actionId from codex_start_thread_compaction. It is passive and should return a bounded status or guidance.
- **codex_get_worker_status** — Read central worker heartbeat and execution-mode state without starting app-server. Use this when health or queue guidance says inspect_worker_health. Next compare with queue and concurrency status.
- **codex_get_queue_status** — Read durable queue state, queued reasons, running operations, and worker assignment. Use this to understand slot pressure or lock waits. Do not retry when queued work already exists.
- **codex_get_concurrency_status** — Read active turn counts and scheduler resource locks. Use this with queue status when diagnosing parallel work. Active locks are not a retry instruction by themselves.
- **codex_get_worker_command_status** — Poll a worker command created by a client-mode control action. Use this for archive, unarchive, compaction, restart, runtime refresh, and delegated lifecycle commands. Keep include_result=false unless the result is needed.
- **codex_restart_app_server** — Restart only the MCP-owned codex-app-server subprocess. Use this only when guidance recommends restart and active work is absent or explicitly handled. In client mode this delegates to the worker command lane.
- **codex_get_app_server_status** — Read MCP-owned app-server status without starting it. Use this with worker, queue, and concurrency status to verify active work. In client mode prefer worker-derived active turns over local guesses.
- **codex_get_runtime_capabilities** — Read compact runtime capabilities, models, permissions, hooks, account state, and supported methods. Use this after health or before new work. In client mode refresh queues a worker command.
- **codex_health_summary** — Read compact MCP readiness and contract metadata. Use this first on startup, reconnect, and after MCP restart. Next inspect runtime capabilities or follow agentGuidance if health is degraded.
- **codex_get_agent_contract** — Read the machine-readable agent guide for this MCP server. Use this when tools/list metadata was unavailable or when a client wants the full contract examples. It is passive and the next normal startup call is codex_health_summary.
- **codex_collect_diagnostics** — Collect a scoped diagnostic snapshot with compact evidence and guidance. Use this before repair when status reports failed, stale, orphaned, or degraded state. It does not execute repairs.
- **codex_get_diagnostic_logs** — Read redacted diagnostic log and app-server audit entries with filters. Use this only for targeted troubleshooting, not normal polling. Raw payload mode is for local audit and remains secret-redacted.
- **codex_analyze_issue** — Analyze scoped diagnostics and recommend safe next actions. Use this after collect_diagnostics or when a human needs a compact root-cause summary. Follow agentGuidance rather than inventing retries.
- **codex_repair_issue** — Run an allowlisted repair action with dry-run first by default. Use this only when diagnostics or agentGuidance recommends a specific action. Stop when loopGuard.allowed is false.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/aresyn-codex-control-plane-mcp/readme_