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, output} while alive; the full result (output, tokens, duration_sec) once finished. While it runs, output.state says how to read silence: exit_only means the agent prints only when it exits (claude does) and is not stuck; quiet means it printed before and then stopped for 15 minutes — tell the user, do not cancel on your own. tail_dispatch(dispatch_id, since=) returns the lines printed so far.
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.