MCP reference

The same core the CLI calls, exposed as typed MCP tools over stdio — for contexts where Bash is not available (claude.ai, Claude Desktop, any MCP client). Read this to know exactly which tools an MCP-connected agent gets and what each one takes.

Register it once:

claude mcp add commission -- commission mcp

Refusals come back in commission’s standard shape — message, missing, and the exact fixing command — marked isError, so a model can correct itself without a human. The MCP surface is deliberately narrower than the CLI: it covers the working loop (claim, record, prove, close) and planning, not project administration or import.

Tools

commission_next

Pick the next ready task and return its full context bundle (body, criteria, dependency state, links, notes, finishing commands). With claim=true it is atomically claimed under a lease — parallel agents always get distinct tasks.

commission_show

Everything needed to work one task, in a single read: body, acceptance criteria, dependency state, parent and children, links, notes from previous sessions, answered decisions, outstanding approvals, and the commands that finish it from where it currently stands. Reach for this when you were handed an id; reach for commission_next when you need to be given work.

commission_board

Project position: in progress, in review, ready frontier, blocked (with blockers), recently done, stale claims.

commission_ready

The parallel frontier: every task workable right now, with claim state, touches-overlap warnings, and suggested no-overlap batches for parallel dispatch.

commission_inbox

What needs a HUMAN’s judgment: outstanding approvals and verifications, finished work waiting to be accepted, work only a person may move, suggested delegations, unresolved external divergences, stale claims, and guidance drift on in-flight work. Ordered by what unblocks the most work. Every item carries why it needs a person, the cost of ignoring it, and the one command that resolves it. This is the counterpart to commission_next — never call it to find your own work.

commission_standup

Brief done / doing / blocked narrative with latest notes, plus a since-7am day digest — what a human would say on a call.

commission_transition

Move a task: in_progress (start; auto-claims), in_review, done, cancelled, open (reopen). done is refused until criteria and gate evidence are satisfied — the refusal says exactly what to attach. cancel requires reason or superseded_by; force requires reason.

commission_claim

Claim a task under a lease (expired claims are reclaimable by anyone).

commission_release

Hand a task back by dropping its lease, leaving it unclaimed on the ready frontier for anyone to take. Use it when you cannot finish — a released task is honest, an abandoned one just waits for its lease to expire. This drops the claim only; it does not change status or undo recorded work.

commission_note

Leave a session breadcrumb on a task — decisions, dead ends, discoveries. The next session reads these.

commission_ask

Escalate a judgement call to a human instead of guessing. Use this the moment a decision is not yours to make — a guess becomes an assumption nobody can trace back, and stopping silently leaves a person wondering why nothing moved. With blocking=true no agent may work the task until it is answered, so reserve that for when work genuinely cannot continue; then pick up something else with commission_next.

commission_answer

Record a human’s decision and the reasoning behind it, resolving an open question and unblocking the task. Refused for agents — answering your own escalation is guessing with extra steps. The reasoning is the durable half: it lands in every later context bundle, so the next session inherits the decision AND why.

commission_approve

Record a human’s acceptance of finished work. Required before done when a task’s autonomy is supervised, and NOT the same as completion: criteria and evidence say the work is finished, an approval says a person accepted it. Refused for agents, and no force flag bypasses it.

commission_heartbeat

Extend your lease on a claimed task without changing its state. Claims expire (8h by default) so a crashed session never wedges work — but a long stretch of implementing writes no commission events, and without a heartbeat it looks abandoned and becomes reclaimable mid-flight. Only the holder may extend.

commission_evidence

Attach completion evidence (pr, commit, benchmark, test, rollback, …) — the real reference, which done then counts against the task’s gate. A placeholder is refused: ‘pending’ is not a commit, and a gate cleared by a word meaning ‘not yet’ is not a gate. If you do not have the reference yet, attach nothing; the refusal on done will name what is still missing. Attaching a kind again corrects it — the earlier value is kept, and readers see the newest.

commission_check

Tick acceptance criterion n on a task, 0-indexed, once it is actually true — not when you intend to make it true. Unchecked criteria are what done refuses on, so this is the running record of how close the work is. Pass done=false to untick one you ticked too early.

commission_apply

Atomically create/update a whole task graph from a plan document (local keys resolve to ids in one transaction; re-apply upserts by key). Use dry_run=true first: full validation and an exact preview, rolled back.

commission_search

Full-text search over task titles, bodies, and notes — ‘did we already decide/try X?’

commission_log

Append-only event feed. Pass after=<cursor> (an event id) to catch up; response includes nextCursor.

commission_prime

The commission operating manual for agents (optionally with a project’s vision embedded).

commission_sync

Observe bound externals (PRs via gh, Jira via a provided observations file), canonicalize status (signals beat claims), record divergences, and return the outbound plan. Execute the plan through YOUR Jira/GitHub access, then call again to confirm zero divergences.

commission_bind

Bind a task to an external object (jira issue or github PR) — the trigger for sync.

commission_define

The project-definition brief: how to turn an idea (or an existing repo) into a vision + task graph, ending in a reviewed commission_apply.