MCP Task Orchestrator

MCP Task Orchestrator

Server-enforced workflow discipline for AI agents.

Prompt-based frameworks hope the LLM follows instructions. This one blocks the call if it doesn't.

Task Orchestrator is an MCP server that gives AI coding agents a persistent work item graph with quality gates enforced by the server, not the prompt. It is built for developers running multi-agent or multi-session coding workflows: an orchestrator dispatching sub-agents, a fresh session picking up yesterday's work, or an autonomous loop draining a backlog. It ships as a Docker image, works with any MCP client, and has an optional Claude Code plugin that adds skills and hooks on top.

New here? Start with the [illustrated field guide](https://jpicklyk.github.io/task-orchestrator/field-guide/). It explains the ideas on this page in short visual pages, several of them interactive: fire triggers at a phase gate, click a work breakdown through its dependencies, and watch a schema resolve.

The Problem

Multi-agent workflows need infrastructure the model doesn't provide. When an orchestrator dispatches sub-agents across sessions, there's no built-in way to enforce what documentation must exist before work starts, track which agent made which change, or guarantee dependency ordering across a work breakdown. These are structural concerns — they belong in the server, not in prompts.

Task Orchestrator puts them in the server. If a required design note isn't filled, advance returns an error naming the missing note. If an upstream dependency isn't complete, the transition is blocked. Every transition and note records who made it. A new session recovers the full state in one call instead of replaying a conversation. And the rules are YAML config, not hardcoded prompts - change them without changing code.

What It Looks Like

Morning — new session, new agent, zero context:

Agent: items_read(select="context") → 2 items in work, 1 blocked, 1 stalled (missing implementation-notes) Agent: items_read(select="history", since="2026-01-14T17:00:00Z") → Recent transitions show orchestrator-1 dispatched 3 sub-agents yesterday

Agent: advance(ops=[{ op: "transition", itemId: "a3f28c01", trigger: "start" }]) -> gate_blocked: "Item a3f28c01-... is missing 1 required notes." (detail.missing: requirements)

Agent: notes_write(ops=[{ op: "upsert", itemId: "a3f28c01", key: "requirements", role: "queue", body: "Validate email format, enforce password complexity..." }]) -> results[0]: { ok: true, id: "...", version: 1, created: true }

Agent: advance(ops=[{ op: "transition", itemId: "a3f28c01", trigger: "start" }]) → queue → work. Caller recorded. No context rebuilding.

Quick Start

Prerequisite: Docker installed and running.

1. Register the server

The simplest setup is a per-session STDIO container: no port, no daemon, no REST API. Add it to your project's .mcp.json:

{

"mcpServers": { "mcp-task-orchestrator": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "mcp-task-data:/app/data", "ghcr.io/jpicklyk/task-orchestrator:latest" ] } } }

Claude Code users can register the same shape from the CLI instead:

claude mcp add-json mcp-task-orchestrator '{

"command": "docker", "args": ["run", "--rm", "-i", "-v", "mcp-task-data:/app/data", "ghcr.io/jpicklyk/task-orchestrator:latest"] }'

Restart your client. The server creates its SQLite database on first run. Without a config file every tool works in schema-free mode: no gates, no required notes. Add schemas when you want enforcement.

2. Enable workflow schemas

Create .taskorchestrator/config.yaml in your project (see Workflow Enforcement for an example, or use the plugin's /task-orchestrator:manage-schemas skill) and mount that folder into the container:

{

"mcpServers": { "mcp-task-orchestrator": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "mcp-task-data:/app/data", "-v", "/absolute/path/to/your/project/.taskorchestrator:/project/.taskorchestrator:ro", "-e", "AGENT_CONFIG_DIR=/project", "ghcr.io/jpicklyk/task-orchestrator:latest" ] } } }

At every start the server imports the mounted file into its database (the server-config-import boot step) and then serves the stored copy; editing the file takes effect on the next restart. If several containers share one data volume but mount different files, the last one to boot wins; use step 3 for multi-project setups.

Use an absolute host path. Claude Code's .mcp.json expands only environment variables (${VAR} and ${VAR:-default}), so editor-style placeholders such as ${workspaceFolder} are not substituted. Only the .taskorchestrator/ folder is exposed; the server has no access to the rest of your project.

3. Multi-project setup (HTTP + config-sync)

If you work across several repositories, run one persistent server with the REST API enabled. Each project's .taskorchestrator/config.yaml then syncs into it automatically through the plugin's config-sync hook: no per-project container, no manual mount, and config changes hot-reload without a restart. The plugin's /task-orchestrator:configure-server skill renders this setup interactively; the manual equivalent is:

docker pull ghcr.io/jpicklyk/task-orchestrator:latest

docker run -d --name mcp-task-orchestrator-http --restart unless-stopped \ -v mcp-task-data:/app/data \ -e MCP_TRANSPORT=http -e API_ENABLED=true -e API_AUTH_MODE=none -e API_ALLOW_UNAUTHENTICATED=true \ -p 127.0.0.1:3001:3001 \ ghcr.io/jpicklyk/task-orchestrator:latest

Register it in .mcp.json using the HTTP shape:

{

"mcpServers": { "mcp-task-orchestrator": { "type": "http", "url": "http://localhost:3001/mcp" } } }

And export the client-side variable that tells config-sync where the server is (without it, config-sync silently does nothing):

export TASK_ORCHESTRATOR_API_URL=http://localhost:3001

Alternatively, a client.json (apiUrl only, no token) supplies the URL. Project-mode /task-orchestrator:init writes it beside the project config, only for a loopback server and only as a bare origin with no path, query or fragment (add .taskorchestrator/client.json to .gitignore, the URL is machine-specific); /task-orchestrator:init --user writes the user-level file, which works for any host. The order is the environment variable, then the project-level file, then the user-level file. /task-orchestrator:init sets up a project root for the current directory, and /task-orchestrator:init --user creates a personal root that serves every directory without its own config.

SECURITY: unauthenticated mode (REST and /mcp alike) means anyone who can reach the port has full

read/write/delete access, as the single local principal. This is only safe because the port is published loopback-only (-p 127.0.0.1:3001:3001).

Never publish it on 0.0.0.0 or a wider interface. For shared or networked deployments use bearer

tokens or JWKS auth — see Fleet Deployment.

Prefer to run without Docker? CONTRIBUTING.md covers building the fat JAR from source.

Core Capabilities

The Phase Model

Every work item has a role: queue (not started), work (in progress), review (optional, opt-in per schema), blocked (an upstream dependency is unmet), and terminal (done or cancelled). Each role maps to one or more configurable statuses. Agents move items with the advance tool's transition op rather than editing status directly, and that call is where every gate is checked. Schemas attach note requirements to roles: a note declared with role: queue must exist before the item can leave the queue phase.

Illustrated: Phase Gates draws the roles and triggers as a track and includes a gate simulator.

Workflow Enforcement

Schemas define what agents must produce at each phase, and the server blocks progression until it's done. They also set a planning floor: when an agent enters plan mode, the schema tells it what documentation must exist before implementation can start, shaping the plan itself.

# .taskorchestrator/config.yaml

work_item_schemas: feature-task: notes:

• key: requirements role: queue required: true description: "Acceptance criteria before starting" guidance: "Cover: problem statement, acceptance criteria, alternatives considered, test strategy." skill: "spec-quality"
• key: implementation-notes role: work required: true description: "What was built and why"

With this schema, advance transition with trigger: "start" from queue requires requirements to be filled. The server returns a gate_blocked error listing exactly which notes are missing.

The guidance field provides authoring instructions surfaced at the right moment: when an agent is about to fill that note, the response names it as guidanceKey (with the skillPointer when the note names a skill), and items_read schema returns the text. The skill field goes further, naming a skill the agent should invoke before filling the note so the evaluation follows a defined framework rather than freeform prose.

Composable Traits

Traits add cross-cutting note requirements to any schema without duplicating definitions. Define a trait once, apply it to any item type:

traits:

needs-security-review: notes:

• key: security-assessment role: review required: true description: "Security review of auth, data handling, and access control" skill: "security-review"

work_item_schemas: feature-task: default_traits:

• needs-security-review notes:

... base notes

Every feature-task item automatically inherits the security-assessment requirement. Traits can also be applied per item via the traits array of an items_write create or update, so a task touching authentication gets needs-security-review while a CSS cleanup doesn't.

Illustrated: Schemas and Traits shows how a type, its default traits and per-item traits resolve into one gate. Seats covers splitting a phase between several agents.

Persistent Work Item Graph

Everything is a WorkItem in a hierarchical graph. Items nest to any depth and are connected by typed dependency edges. Create an entire work breakdown atomically:

{ "ops": [{

"op": "create_tree", "root": { "title": "User Authentication", "type": "feature-task" }, "children": [ { "ref": "schema", "title": "Database schema", "type": "feature-task" }, { "ref": "api", "title": "Login API", "type": "feature-task" }, { "ref": "tests", "title": "Integration tests", "type": "feature-task" } ], "deps": [ { "from": "schema", "