MCP tools
The daemon serves MCP at http://127.0.0.1:8765/mcp. Nine self-describing MCP tools cover the job lifecycle:
| Tool | Purpose |
|---|---|
submit |
Queue a job with a workflow and prompt, or pass from_job to copy a finished job. With from_job, only target and fresh may be set. |
get |
Read a job without waiting: its result, pending question, and attempts |
wait |
Block until any of 1 to 16 listed job_ids finishes or asks a question |
cancel |
Stop a queued or running job; returns cancel_status |
answer |
Reply to a worker’s pending question |
list |
Active and recent jobs, workflows, profiles, and guidance for a project |
card_create, card_move, card_list |
Track work on a per-repository board |
Jobs are admitted first in, first out, up to max_jobs across all projects. Several jobs in one project can run at once and edit the same checkout. Jobs that share a project, session, workflow, and target run one at a time.
wait and get return {job, result, truncated, result_path, pending_question, failure_kind, next_target, model, duration_ms, tokens}; get adds attempts. A response stays below 9,000 UTF-8 bytes. A longer result is truncated and carries truncated: true and result_path; read the full text from that file. cancel returns {job, cancel_status}: terminated for a queued job, requested for a running job, and already_terminal for a finished job, which is never changed.
Recovery and Routing
submit(from_job=X)runs a finished job again onnext_target, the next healthy target in profile order after the source job’s last attempt.submit(from_job=X, target=Y)pins a target. The source job must be terminal and not pruned.freshdefaults to null. Withoutfrom_job, null means false. Withfrom_job, omittingfreshcopies the source job’s value, and an explicitfresh=falseoverrides a source job that usedfresh=true.- When an attempt is
replay_safe, the server retries on the same target whenretry.codesorretry.patternsmatch, opens a fresh session oncontext_overflow, and falls back to the next target, all inside the same job. Each step is oneattemptsrow withreasonretry,fresh_session, orfallback. - An attempt is
replay_safeonly when the target streams events, notool.startedevent occurred, and the worker asked no question. A failed attempt that is notreplay_safeis not recovered automatically, so the job ends failed; inspect the checkout before callingsubmit(from_job=...). An attempt that is notreplay_safecan still succeed. - After a daemon restart,
runningjobs areinterrupted,openquestions areexpired, andqueuedjobs resume. Nothing re-runs by itself. - An open circuit skips a target until its cooldown ends. When no target is available, the error is
targets_unavailablewithretry_after_s. - Errors return
code,message, andnext_action.invalid_requestmeans the arguments did not match the schema or named an unknown target.
The full contract for Coordinator agents is in tool-contract.md.
Worker questions
Each worker gets REFRACT_ASK_URL and REFRACT_ASK_TOKEN in its environment. Running refract ask "<question>" blocks until the Coordinator calls answer or ask_timeout_s passes. The worker’s tool shell must have refract on PATH.
Source: server/README.md