MCP Task Orchestrator · Field guidePlate 5 of 10
One Docker image, one SQLite file. It runs as a throwaway container per session or as a persistent local server shared by every project, and one tool dispatcher answers the MCP tools and the REST tool route, so the same gate logic and the same response envelope serve both.
api, service, read, run, knowledge, config, support, telemetry, port, plus top-level decision, report and upgrade) that a second test keeps free of cycles. A separate bootstrap package wires everything once at startup and no layer imports it. The REST route POST /api/v1/ops/{tool} runs the same tool dispatcher as MCP, so a call to advance an item gets the same answer on either interface./mcp path needs the same Authorization: Bearer credential as the REST API. Without one, the server serves only the local principal, so keep it on loopback or behind your own network controls.Over HTTP the server mounts /mcp (orchestration), /mcp/knowledge (a smaller read and write set) and /mcp/director (read tools, run control and decisions, no read that returns a note or document body). Over stdio one profile is served, picked by MCP_TOOL_PROFILE. Any other value fails startup.
With API_ENABLED=true and API_AUTH_MODE=bearer or jwks, every /mcp* path requires the credential. HTTP with API_ENABLED=false needs MCP_ALLOW_UNAUTHENTICATED=true or startup fails. A director credential reaches only the director path.
Flyway is the only schema path (SCHEMA_MODE is migrate or validate), under a <db>.migrate.lock file lock, then data steps such as server-config-import run. The readiness marker at READINESS_FILE is written only after all of that and the transport bind. Depth is in fleet-deployment.md.
Dashboards, CI jobs and the plugin's own hooks use HTTP under /api/v1, switched on with API_ENABLED=true. Every tool is reachable as POST /api/v1/ops/{tool}, so an advance over REST is the same call, with the same gate logic, as over MCP.
| Auth mode | How a caller proves itself |
|---|---|
bearer | Static tokens from a secrets file. Each has its own capabilities, scope and expiry. Loaded at startup. |
jwks | Signed JWTs checked against a key set, issuer and audience. Capabilities and scope travel as claims. |
none | An explicit double opt-in. Every request acts as admin. For a loopback port only. |
| Capability | Allows |
|---|---|
read | Every GET, the event stream, and the read tools |
write-items, write-notes | Creating, editing and deleting items and notes |
advance | Role transitions |
manage-dependencies | Adding and removing edges |
write-config | The config ops push, rollback and reset (not docs_write) |
write-docs | Every docs_write op, plans and rules included |
runs | Every runs_write op except ack and answer |
decide | Answering decisions: ack and answer |
admin | All of the above, plus attribution fields and lease overrides |
A token can also be limited to certain project roots and tags. A single item outside that scope returns 403, and lists are filtered.
| To do this | Route under /api/v1 |
|---|---|
| Call any tool: read, write, advance, config, runs, reports | POST /ops/{tool}, with select or ops[] in the body |
| Call a director-profile tool | POST /ops/director/{tool} |
| Fetch an item, or its children and notes | GET /items/{id} · GET /items/{id}/children · GET /items/{id}/notes[/{key}] |
| Get the config JSON Schema | GET /config/schema |
| Inspect or release leases, and read their history | GET /resources/leases · DELETE /resources/leases/{key} · GET /resources/leases/history |
| Follow changes live | GET /events |
| Server info and liveness (health needs no auth) | GET /info · GET /health |
| Discover the server (mounted at the root, outside /api/v1) | GET /.well-known/mcp-task-orchestrator.json |
seq of the events table (above 10^12), so a resume replays from the table, not from memory. Event types: item.created, item.updated, item.deleted, item.advanced, note.upserted, note.deleted, note.ownership_transferred, dependency.added, dependency.removed, scope.entered, scope.left, run.opened, run.updated, run.paused, run.resumed, run.ended, run.marked, seat.ended, decision.raised, decision.acknowledged, decision.answered and decision.withdrawn. Two control events always arrive, whatever the type filter: sync.lost and auth.expired.A write may pass expectedVersion, so a stale client gets a 409 version_conflict and cannot overwrite. Each element of ops[] may carry an idempotencyKey, kept for 24 hours per principal, tool and key, so a retry replays its first result. An Idempotency-Key header is a 400 invalid_request.
Every tool answer is { ok, data | error, meta: { reqId } }, and an error is { code, kind, message, detail?, fix?, retryAfterMs? }. Write calls are non-atomic by default, so a failed element, a failed gate included, answers 207 partial_failure with its own code (for a gate, gate_blocked and the missing notes) in its data.results[i] element. In an atomic: true batch the failing element's error is the answer, so a failed gate there is 409 gate_blocked. The reqId also keys the call log and the server log lines for that call.
The caller is always the credential's principal, on REST and on /mcp alike, and an actor in the body is refused as unknown_parameter. A REST advance is bound by claim ownership and by leases, as on MCP. Lease administration and the event stream exist only here. report (usage, gates, notes, contention, waste and rollup aggregates over server telemetry) is served at POST /ops/report and, over MCP, only on the director profile.
The server works with any MCP client. The plugin wires it into a Claude Code session through hooks, in the order a feature normally unfolds.
| More hooks | What each does |
|---|---|
| Before a note is written | If the note's schema names a skill and the body looks thin, suggests running that skill first. Advisory only. |
| Before an agent is dispatched | Denies a dispatch that is missing a model or an effort, because the shipped agents would silently inherit the caller's model and carry no effort. |
When config.yaml changes | Re-syncs the project config to the server mid-session. |
| After a plan is approved | Stores the plan as a plan document over REST, so items are materialized from it. |
| When a run closes, or a turn ends | Dispatches or nudges a retrospective for a closed run that has not had one. |
| In a director session | Keeps the session at altitude (no file reads or foreground work), re-asserts that after a compaction, and pushes a notice when a decision is waiting. |
| Skills, by purpose | Slash commands under /task-orchestrator: |
|---|---|
| Get set up | quick-start (guided onboarding) · init (project or personal root) · configure-server (transport, REST, config-sync) · adopt-project-scope (migrate an existing database) |
| Shape the rules | manage-schemas (create, edit and validate schemas, traits and identity policy) |
| Day-to-day work | work-summary (dashboard) · create-item · status-progression (which trigger, what is missing) · dependency-manager · batch-complete |
| Run many items | run-wave (attended) · ralph (unattended queue drain) |
| Improve the process | session-retrospective · review-proposals |
Also shipped: agent definitions for implementer, reviewer, planner, test author and director, the orchestrate and director skills, and workflow scripts for audit, wave implementation, retrospective analysis and wave review. Plate 9 covers how they run a feature.
When a schema declares seats (plate 4), run-wave reads them to build each item's stages and picks the agent and model for each seat. The stop guard is seat-aware too: it only sends a sub-agent back for notes its own seat owns.
| Topology | Claims | Fits |
|---|---|---|
| Pure orchestration | None | Single developer, sequential pipelines |
| Pure claim, flat items | Every item | Independent parallel work with no hierarchy |
| Pure claim, chains | Every item | Rarely. When a blocker completes, every agent races for the next link. |
| Hybrid: claim the parent, orchestrate the sub-tree | Feature level only | Feature-based development with many agents |
claimed: true; a claim_held error (pick another item); a select with no match (claimed: false, no reason: stop or wait); and a select with a reason (claim_held or dependency_unmet: matches exist but none can be claimed now, retry after retryAfterMs). A claim belongs to one principal and assignment, and taking a new claim releases the caller's other claims (one at a time). Each element may carry an idempotencyKey.
Any transition into terminal clears the claim, and a reopened item starts unclaimed. A crashed agent's claim simply expires. Nothing has to clear it: a background sweep only records the expiry event.
Lists and searches show only whether an item is claimed. The holder's identity appears in one place: the claimDetail of items_read context for that item.
/mcp. The recorded actor is the principal's audited id (api:<id> or local) with kind external, and a verification of api-jwks, api-bearer or local.API_ENABLED=true API_AUTH_MODE=jwks API_JWKS_URL=https://idp.example/.well-known/jwks.json API_JWKS_ISSUER=https://idp.example API_JWKS_AUDIENCE=task-orchestrator API_JWKS_ALGORITHMS=EdDSA,RS256
| Setup | The caller of /mcp is |
|---|---|
| stdio | local |
HTTP, REST API off, MCP_ALLOW_UNAUTHENTICATED=true | local |
| HTTP, REST API off, no opt-in | The server refuses to start. |
API_AUTH_MODE=none | local |
API_AUTH_MODE=bearer | api: and the token's id |
API_AUTH_MODE=jwks | api: and the JWT's sub |
Every stdio or local-mode session is the same local caller, so they share claims and note ownership and never contend. Telling agents apart takes a credential or a run seat token for each.
An MCP session is bound to the principal that opened it, and another principal on that session gets a 401. A director credential reaches only the director endpoint. A wrong token is the JSON error envelope, not a JSON-RPC error.
No request carries an actor or a proof any more. A leftover actor_authentication: or auditing: block in the server config, or a set DEGRADED_MODE_POLICY variable, fails startup rather than being ignored.
API_JWKS_MAX_STALE_SECONDS is how old a cached key set may be and still be served after a failed refresh (default the larger of an hour and the cache TTL). Past it, requests get 503 unavailable. API_JWKS_URL must be https and resolve only to public addresses, so a private or Docker-network host is refused. Loopback over plain http is allowed only with API_JWKS_ALLOW_INSECURE_URL=true.
The report tool aggregates the server's own call log and events into usage, gates, notes, contention, waste and rollup views, for a director or a dashboard.
A pruner trims tables on a schedule: RETENTION_EVENTS_DAYS (180), RETENTION_AUDIT_EVENTS_DAYS (0), RETENTION_LEASE_HISTORY_DAYS (365) and RETENTION_CALL_LOG_DAYS (90). A value of 0 keeps that data forever. Details are in fleet-deployment.md.
Always on. Transitions, gates, dependencies and cascades work with no further setup.
Opt-in. Agents take time-limited ownership of an item with the claim op of advance. The server then fences the item to its holder: a transition, note write, item update or dependency write by anyone else is not_claim_holder.
Opt-in and separate from claims. With a bearer or JWKS mode, REST and every /mcp* path require a credential, so attribution is proven and no longer shared. Without one, HTTP with the REST API off must opt in with MCP_ALLOW_UNAUTHENTICATED=true.