Codex Control Plane MCP server

Codex Control Plane MCP

English | Русский

<!-- mcp-name: io.github.aresyn/codex-control-plane-mcp -->

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:

read-only, MCP raises that turn to workspace-write and reports the adjustment in status output;

• 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

• keep state/, logs/, .env, and .codex/ private.

What it does

Shortened. The full README is on GitHub.