MCP Task Orchestrator · Field guidePlate 5 of 10

Where it runs and who talks to it

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.

Inside the server

Claude Code + plugin Any MCP client Dashboards · CI · hooks MCP over STDIO or Streamable HTTP REST + SSE Interfaces · MCP tools items, notes, deps, advance, docs, config, runs Interfaces · REST API optional · POST /ops/{tool} Infrastructure SQLite + FTS5 · Exposed ORM · Flyway migrations · YAML config · JWKS Application gates, cascades, config resolution, claims, runs Domain WorkItem · Note · Dependency · roles · transition policy
Each layer may depend only on the layers below it, and an architecture test fails the build on a new violation. The application layer is split into sub-packages (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.

Two ways to run it

Per-session container (STDIO)

MCP client one session stdin / stdout Container docker run --rm -i reads, writes mcp-task-data SQLite volume .taskorchestrator/ optional read-only mount No port, no daemon. The data outlives the container.
The simplest setup. Schemas come from the mounted folder, or the server runs schema-free with no gates.

Persistent server (HTTP + config-sync)

project A session project B session project C session /mcp for tools /api/v1 for config-sync One container 127.0.0.1:3001 per-root config store mcp-task-data Each session's hook pushes its project's config.yaml on start. Unauthenticated mode is for loopback only.
One server for every repository, each with its own schemas, reloaded without a restart. Under a bearer or JWKS credential mode, every /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.

Tool profiles

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.

Auth follows the REST setting

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.

Startup is gated

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.

The REST API, for everything that is not an agent

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 modeHow a caller proves itself
bearerStatic tokens from a secrets file. Each has its own capabilities, scope and expiry. Loaded at startup.
jwksSigned JWTs checked against a key set, issuer and audience. Capabilities and scope travel as claims.
noneAn explicit double opt-in. Every request acts as admin. For a loopback port only.
CapabilityAllows
readEvery GET, the event stream, and the read tools
write-items, write-notesCreating, editing and deleting items and notes
advanceRole transitions
manage-dependenciesAdding and removing edges
write-configThe config ops push, rollback and reset (not docs_write)
write-docsEvery docs_write op, plans and rules included
runsEvery runs_write op except ack and answer
decideAnswering decisions: ack and answer
adminAll 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 thisRoute under /api/v1
Call any tool: read, write, advance, config, runs, reportsPOST /ops/{tool}, with select or ops[] in the body
Call a director-profile toolPOST /ops/director/{tool}
Fetch an item, or its children and notesGET /items/{id} · GET /items/{id}/children · GET /items/{id}/notes[/{key}]
Get the config JSON SchemaGET /config/schema
Inspect or release leases, and read their historyGET /resources/leases · DELETE /resources/leases/{key} · GET /resources/leases/history
Follow changes liveGET /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
Dashboard Server GET /api/v1/events?types=item.advanced,note.upserted an event for each matching change, each with a durable id connection drops reconnect with Last-Event-ID: <last id> the missed events, replayed from the events table If the cursor cannot be satisfied, the first event is sync.lost and the client refetches.
Event ids are the durable 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.

Writes are guarded

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.

Errors say what to do

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.

Where REST differs from MCP

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.

What the Claude Code plugin adds

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.

  1. SessionStartInjects workflow conventions and project scope. Syncs the project config to the server.
  2. EnterPlanModeReads existing items and schema gates first, so the plan covers what the gates will ask for.
  3. ExitPlanModeTurns the approved plan into items, dependency edges and queue notes before any code is written.
  4. SubagentStartHands an implementer or reviewer its protocol: enter your phase, fill its notes, return.
  5. advanceRecords which phase a sub-agent entered, and hints the dispatch profile (agent, model, effort) for the next one.
  6. SubagentStopSends a sub-agent back if the phase it entered still has required notes missing.
More hooksWhat each does
Before a note is writtenIf the note's schema names a skill and the body looks thin, suggests running that skill first. Advisory only.
Before an agent is dispatchedDenies 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 changesRe-syncs the project config to the server mid-session.
After a plan is approvedStores the plan as a plan document over REST, so items are materialized from it.
When a run closes, or a turn endsDispatches or nudges a retrospective for a closed run that has not had one.
In a director sessionKeeps 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 purposeSlash commands under /task-orchestrator:
Get set upquick-start (guided onboarding) · init (project or personal root) · configure-server (transport, REST, config-sync) · adopt-project-scope (migrate an existing database)
Shape the rulesmanage-schemas (create, edit and validate schemas, traits and identity policy)
Day-to-day workwork-summary (dashboard) · create-item · status-progression (which trigger, what is missing) · dependency-manager · batch-complete
Run many itemsrun-wave (attended) · ralph (unattended queue drain)
Improve the processsession-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.

Push or pull

Orchestration, the default

Orchestrator advance item 1sub-agent item 2sub-agent item 3sub-agent One dispatcher, so no two agents race for an item.
The orchestrator pushes items through phases. No identity setup. Fits a single developer or a sequential pipeline.

Claim at the parent, opt-in

Agent 1 Agent 2 claim claim Feature X · TTL 900 s Feature Y · TTL 900 s child child child child hidden Children are advanced by the agent holding the parent claim.
Many agents pull work. A claim is a lease that expires on its own if its holder crashes, and a heartbeat at half the TTL keeps it alive. The recommended fleet shape.
TopologyClaimsFits
Pure orchestrationNoneSingle developer, sequential pipelines
Pure claim, flat itemsEvery itemIndependent parallel work with no hierarchy
Pure claim, chainsEvery itemRarely. When a blocker completes, every agent races for the next link.
Hybrid: claim the parent, orchestrate the sub-treeFeature level onlyFeature-based development with many agents

Claims in practice

Four answers to a claim

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.

Claims clean up after themselves

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.

Who holds it stays private

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.

How the server knows the caller

Local no credential is checked every caller is "local" Token a token-file credential the holder is api:<id> Verified a signed JWT, checked against a key set the holder is api:<sub> Fail-closed bad token: 401 key set unavailable: 503 never a guessed identity
The caller is the principal its transport established, never a field in the request. The same credential works on REST and on /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
SetupThe caller of /mcp is
stdiolocal
HTTP, REST API off, MCP_ALLOW_UNAUTHENTICATED=truelocal
HTTP, REST API off, no opt-inThe server refuses to start.
API_AUTH_MODE=nonelocal
API_AUTH_MODE=bearerapi: and the token's id
API_AUTH_MODE=jwksapi: and the JWT's sub

Local is one principal

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.

Sessions stick to a caller

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.

Old identity settings stop startup

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.

JWKS stays fail-closed

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.

Reports read telemetry

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.

Old data ages out

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.

Three independent switches

Orchestration

Always on. Transitions, gates, dependencies and cascades work with no further setup.

Claims

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.

Credentials

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.