aresyn/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
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:
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:
Use steer_turn only while the target turn is active. For a completed thread,
use send_message instead.
Fork a thread:
Start work in the fork right away:
Use client_request_id for retry-safe fork requests. Without it, each call is
treated as a new fork request. threadId in operation status is the forked
thread; the source thread is reported in forkState.sourceThreadId.
Manage thread lifecycle:
Archive and unarchive are audit actions around app-server thread/archive and
thread/unarchive. They refuse to run while the thread has an active turn or a
pending interaction. Compaction uses its own lightweight actionId because
thread/compact/start is asynchronous. Public thread/delete is intentionally
not exposed.
Ask for a structured final report:
output_schema is passed to app-server turn/start and is tracked by a schema
hash in status output. Object schemas must use the strict form required by Codex:
set additionalProperties to false. MCP stores the final assistant message
as readable text, then parses JSON object output into finalReport.structured
when Codex returns valid JSON. Plain text still works and stays available in
finalReport.text.
MCP does not extract hidden chain-of-thought and does not store raw tool
payloads or command output in final reports.
Drive Plan Mode:
Plan Mode has a runtime floor. The public default write policy is still
read-only and on-request, but Plan Mode needs a writable workspace on
Windows. If the caller or server default resolves to read-only, MCP sends
workspace-write to codex-app-server and returns requestedSandbox,
effectiveSandbox, and runtimePolicyAdjusted in workflow and operation
status.
Mirror a workflow goal into Codex Desktop when the client has one:
MCP writes a thread goal only when the client passes goal. Managed goals use
clear after completion by default. Use set_complete or leave when the goal
should remain visible after the workflow ends. Normal workflow polling is
passive; use refresh_live_goal=true only when you want MCP to call live
app-server goal methods.
Run a Codex code review:
Or let MCP create a service thread for a local checkout:
Review workflows do not write files by themselves. They run inside the selected
Codex sandbox and approval policy. Use client_request_id when a caller may
retry the start request after a transport timeout.
Handle approvals and questions:
Start diagnostics with:
Repair actions default to dry_run=true.
Status and diagnostic tools also return agentGuidance and
agentGuidanceText when MCP sees a blocker, failed state, stale run, pending
interaction, duplicate prompt, auth problem, rate limit, or unsafe recovery
loop. Agents should follow agentGuidance.instructions before deciding to