Server data from the Official MCP Registry
Durable MCP control plane for long-running Codex Desktop tasks.
Durable MCP control plane for long-running Codex Desktop tasks.
Valid MCP server (1 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.
3 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: CODEX_HOME
Environment variable: CODEX_PROJECTS_ROOT
Environment variable: CODEX_ALLOWED_ROOTS
Environment variable: CODEX_PROJECTS_REGISTRY
Environment variable: CODEX_MCP_STATE_DB
Environment variable: CODEX_CONTROL_PLANE_MCP_LOG
Environment variable: CODEX_MCP_HOOK_HISTORY_ENABLED
Environment variable: CODEX_MCP_HOOK_HISTORY_MAX_TEXT_CHARS
Environment variable: CODEX_KB_HISTORY_PROJECTS_ROOT
Environment variable: CODEX_BINARY_PATH
Environment variable: CODEX_MCP_DEFAULT_SANDBOX
Environment variable: CODEX_MCP_DEFAULT_APPROVAL_POLICY
Environment variable: CODEX_MCP_DEFAULT_MODEL
Environment variable: CODEX_MCP_DEFAULT_EFFORT
Environment variable: CODEX_MCP_APPROVAL_RESPONSE_TIMEOUT_SECONDS
Environment variable: DEEPSEEK_ENV_PATH
Environment variable: DEEPSEEK_SUMMARY_ENABLED
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-aresyn-codex-control-plane-mcp": {
"args": [
"codex-control-plane-mcp"
],
"command": "uvx"
}
}
}From the project's GitHub README.
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.
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:
| Capability | Thin Codex wrapper | Codex Control Plane MCP |
|---|---|---|
| Multi-hour tasks | blocking / fragile | durable async operation |
| Client timeout recovery | manual | retry-safe client_request_id |
| Duplicate turn protection | no | active prompt detection |
| Plan Mode workflow | human / manual | pollable workflow state |
| Approvals and questions | blocking / opaque | pending interactions API |
| Restart recovery | ad hoc | persisted operation state |
| Diagnostics | logs only | health, diagnostics, repair tools |
codex-app-server.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 for untrusted repositories;on-request approval when testing new workflows;state/, logs/, .env, and .codex/ private.client_request_id handling.thread/start or turn/start.threadId/turnId, operationId, or workflowId.Write and control actions go through codex-app-server. The server does not
mutate Codex internal SQLite databases or transcript files.
Recommended:
pipx install codex-control-plane-mcp
Or run directly:
uvx codex-control-plane-mcp
From GitHub:
python -m pip install "codex-control-plane-mcp @ git+https://github.com/aresyn/codex-control-plane-mcp.git"
For local development:
git clone https://github.com/aresyn/codex-control-plane-mcp.git
cd codex-control-plane-mcp
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest -q
After installation, generate a config:
codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects
Minimal stdio entry:
{
"mcpServers": {
"codex-control-plane": {
"command": "codex-control-plane-mcp",
"args": []
}
}
}
Run the MCP stdio server:
codex-control-plane-mcp
Or run it as a module:
py -m codex_control_plane_mcp.server
The old openclaw-codex-mcp and openclaw-codex-mcp-hooks commands remain as
compatibility aliases for one release line.
The admin helper can generate a fuller client config, install hooks, and run a protocol smoke:
codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects
The command prints a JSON block you can copy into an MCP client config. It does not print secrets or private prompts.
You can also install only the Codex hooks:
codex-control-plane-mcp-hooks install --state-db .\state\codex-mcp-state.sqlite3
codex-control-plane-mcp-hooks status
codex-control-plane-mcp-hooks doctor
The installer backs up ~/.codex/hooks.json, merges its handlers with your
existing hooks, stores stateDb as an absolute path, and writes prompts, visible
agent progress text, final answers, and turn status into the MCP state DB. Tool
calls and command outputs are not recorded by default. Restart Codex after
installing or changing hooks.
For turns launched through codex-app-server, the server mirrors the accepted
prompt, visible assistant messages, and turn status into the same SQLite
history. That keeps search and status reads useful even when app-server does not
execute user hooks itself.
Submit a durable task:
codex_submit_task
-> operationId
codex_get_operation_status(operationId)
-> queued / running / waiting_for_approval / completed / failed
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.
Drive Plan Mode:
codex_start_plan_workflow
-> workflowId
codex_get_workflow_status(workflowId)
-> wait_plan / review_plan / execute_plan
codex_approve_plan(workflowId)
-> executionOperationId
codex_get_workflow_status(workflowId)
-> finalReport
Handle approvals and questions:
codex_list_pending_interactions
codex_answer_pending_interaction
Start diagnostics with:
codex_health_summary
codex_collect_diagnostics
codex_analyze_issue
codex_repair_issue
Repair actions default to dry_run=true.
Stable orchestration tools:
codex_submit_taskcodex_get_operation_statuscodex_start_plan_workflowcodex_get_workflow_statuscodex_approve_plancodex_list_pending_interactionscodex_answer_pending_interactioncodex_interrupt_turncodex_health_summarycodex_collect_diagnosticscodex_repair_issueCompatibility and read tools:
codex_start_chatcodex_send_messagecodex_execute_plancodex_list_projectscodex_list_project_chatscodex_list_active_chatscodex_search_chatscodex_get_chat_statuscodex_get_chatcodex_get_turn_statuscodex_restart_app_servercodex_get_app_server_statuscodex_get_diagnostic_logscodex_analyze_issueNew clients should use durable operations and workflows. Low-level write tools stay available for compatibility.
See docs/API_CONTRACT.md for schemas, error shape, stable tool groups, and versioning rules.
Every tool declares an outputSchema and returns MCP structuredContent.
Success:
{"ok": true}
Domain or tool error:
{
"ok": false,
"error": {
"code": "CODEX_ERROR_CODE",
"message": "Human readable message",
"details": {},
"retryable": false
}
}
Call codex_health_summary on startup and reconnect. The version block
contains serverName, serverVersion, contractVersion, toolSurfaceHash,
and stable/compatibility tool lists.
Configuration can come from environment variables or from a JSON file referenced
by CODEX_CONTROL_PLANE_MCP_CONFIG. The old OPENCLAW_CODEX_MCP_CONFIG name is
still accepted as a fallback.
Common variables:
CODEX_HOME: Codex home directory. Defaults to %USERPROFILE%\.codex.CODEX_PROJECTS_ROOT: project root scanned by catalog and read tools.CODEX_ALLOWED_ROOTS: semicolon-separated path allowlist.CODEX_PROJECTS_REGISTRY: optional JSON project registry.CODEX_MCP_STATE_DB: local MCP state DB.CODEX_CONTROL_PLANE_MCP_LOG: log file path.CODEX_MCP_HOOK_HISTORY_ENABLED: enables SQLite hook history. Defaults to true.CODEX_MCP_HOOK_HISTORY_MAX_TEXT_CHARS: per-message hook capture limit.CODEX_KB_HISTORY_PROJECTS_ROOT: optional legacy normalized KB history root.CODEX_BINARY_PATH: optional explicit Codex binary path.CODEX_MCP_DEFAULT_SANDBOX: default write sandbox. Defaults to danger-full-access.CODEX_MCP_DEFAULT_APPROVAL_POLICY: default write approval policy. Defaults to never.CODEX_MCP_DEFAULT_MODEL: default Codex model passed to app-server.CODEX_MCP_DEFAULT_EFFORT: default effort level.CODEX_MCP_APPROVAL_RESPONSE_TIMEOUT_SECONDS: pending interaction timeout.DEEPSEEK_ENV_PATH: optional .env file for DeepSeek summary settings.DEEPSEEK_SUMMARY_ENABLED: enables or disables remote summary calls.The write policy values are defaults, not hard limits. A client call can pass
sandbox or approval_policy explicitly, for example to run one task in
read-only or on-request mode.
Example:
$env:CODEX_CONTROL_PLANE_MCP_CONFIG = Join-Path (Get-Location) "examples\codex-control-plane-mcp.config.json"
$env:CODEX_MCP_DEFAULT_SANDBOX = "danger-full-access"
$env:CODEX_MCP_DEFAULT_APPROVAL_POLICY = "never"
py -m codex_control_plane_mcp.server
See examples/codex-control-plane-mcp.config.json.
The server is built for common local orchestration failures:
client_request_id.thread/start and turn/start.These cases are stored in durable operation, workflow, turn, hook, and pending
interaction state. Terminal statuses are explicit.
unknown_after_app_server_exit is not treated as success.
MCP LIVE TEST / DO NOT MODIFY FILES.dry_run=true.restart_app_server_idle.Fast local checks:
python -m pytest -q
python -m compileall -q openclaw_codex_mcp codex_control_plane_mcp tests scripts
git diff --check
Protocol-only MCP smoke:
python .\scripts\mcp_live_smoke.py --scenario protocol
Safe live smoke with real Codex Desktop/app-server:
python .\scripts\mcp_live_smoke.py --scenario safe-operation --cwd <PROJECT_ROOT>
Full live regression:
python .\scripts\mcp_live_smoke.py --scenario full --safe-restart --cwd <PROJECT_ROOT>
See docs/RELEASE_CHECKLIST.md. For public launch positioning, see docs/PUBLICATION_GUIDE.md.
Build locally:
python -m pip install build
python -m build
The wheel includes the MCP server, the hook installer, the admin helper, and the bundled Codex hook module.
The normal install path is:
pipx install codex-control-plane-mcp
or:
uvx codex-control-plane-mcp
Read CONTRIBUTING.md and SECURITY.md before opening issues that include diagnostics.
Good GitHub topics for this repo:
python, mcp, mcp-server, model-context-protocol, openai-codex,
codex, codex-desktop, agent-tools, ai-agents, developer-tools,
automation, orchestration, agentic-workflows, long-running-tasks,
openclaw, hermes, hermes-agent.
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.