central-mcp

central-mcp — agentOS Orchestration Guide

central-mcp is the portfolio PM for someone running many agent-driven projects at once. Each registered project is bound to a coding-agent CLI (claude / codex / gemini / opencode / droid / hermes / openclaw / gjc). If cmcp install <you> has been run, its MCP tools are registered as the central server and you can call them natively.

Prefer these tools over raw shell commands whenever the work targets a registered project: dispatches get logging, history, token accounting, quota-aware fallback, and observation surfaces for free. Use your shell for ad-hoc work outside the registry.

Core loop

1. list_projects — see the portfolio (name, agent, path, tags). Pass workspace="__all__" for every workspace.
2. dispatch(name, prompt) — run the project's agent non-interactively in its cwd. Non-blocking: returns a dispatch_id in <100 ms while the agent works in the background.
3. check_dispatch(dispatch_id) — poll. {status: "running", elapsed_sec} while alive; the full result (output, tokens, duration_sec) once finished.
4. cancel_dispatch(dispatch_id) — abort a runaway dispatch.

dispatch(name="my-app", prompt="Run the test suite and fix any failures")
→ {dispatch_id: "a1b2c3d4"}
check_dispatch(dispatch_id="a1b2c3d4")
→ {status: "running", elapsed_sec: 42.0}   # later: full result

Coding dispatches routinely take 1–15 minutes. Do not busy-wait: check once ~every 3 s only if the user is waiting on the answer; otherwise report the dispatch_id, move on, and re-check on your next turn, heartbeat, or cron tick. Every central-mcp tool response also piggybacks completions that finished since your last call, so any later tool use surfaces finished work automatically.

Fan-out

dispatch(name="@workspace-name", prompt=...) sends one prompt to every project in that workspace at once and returns one dispatch_id per project. Good for portfolio-wide chores ("update CI config", "audit dependencies").