MCP Task Orchestrator
MCP server with a work item graph and server-side gates: an agent cannot start work until the required notes exist
- 214 ★ on the repository
- Last commit
Extended access
Why this level
- The server stores the task graph and notes in SQLite on a Docker volume and changes them on agent calls
- Open HTTP mode with no authentication gives full access to anyone who reaches the port, so keep the port on 127.0.0.1
Install
- Works in
Manual install
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"]}'Per-session stdio container; Docker must be running.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The server stores the task graph and notes in SQLite on a Docker volume and changes them on agent calls
- Open HTTP mode with no authentication gives full access to anyone who reaches the port, so keep the port on 127.0.0.1
This is third-party code. Review the repository files before installing.
What it does
Task Orchestrator is an MCP server that gives agents a persistent work item graph with quality gates enforced by the server rather than the prompt. It is built for multi-agent and multi-session workflows: an orchestrator dispatches work to sub-agents, a fresh session picks up yesterday's work, an autonomous loop drains a queue. Each item has a role: `queue`, `work`, `review`, `blocked` or `terminal`. The agent moves items with the `advance` tool. If a required note is missing the call returns an error naming it, and if an upstream dependency is unfinished the transition is blocked. Every transition and note records who made it, the rules live in YAML, and a new session restores the state with one `items_read` call. Storage is SQLite and the delivery is a Docker image.
Who it is for. Developers running several agents or sessions who need a shared work queue with required notes and dependency ordering.
Good fit when
- An orchestrator dispatches a broken-down task to sub-agents and dependencies hold the execution order
- In the morning a new session reads the context and learns that two items are in work, one is blocked and one is stalled
- Before work starts the agent must fill a requirements note, otherwise `advance` returns an error
- You want to trace which agent made each transition and each note
Not a fit when
- A plain text to-do list is enough: the item graph, roles and YAML schemas are overkill for a short task
- Docker is unavailable on the machine: the server ships as an image and building from source is described separately in CONTRIBUTING.md
- You need a shared networked install without configuring authorization: open mode is safe only on loopback
Example request
Show the work item context: what is in work, what is blocked and what is missing for the next phase transitionMCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
MCP_TRANSPORT- The value http enables HTTP mode instead of stdio
AGENT_CONFIG_DIR- Project folder with `.taskorchestrator/config.yaml` inside the container
Limitations
Docker is required and the image `ghcr.io/jpicklyk/task-orchestrator:latest` keeps data in SQLite on a volume. Without a `.taskorchestrator/config.yaml` file the schema-free mode runs: no gates and no required notes. The config file is imported on every start, and with several containers on a shared volume the last one to boot wins. In HTTP mode with `API_AUTH_MODE=none` the port gives full access to anyone who can reach it, so publishing it is acceptable only on `127.0.0.1`, and shared installs have tokens and JWKS. The license is MIT.
How to disable. Remove the registration from `.mcp.json` or with `claude mcp remove mcp-task-orchestrator`, stop the container and delete the `mcp-task-data` volume if needed.
FAQ
How do I connect Task Orchestrator to Claude Code?
With `claude mcp add-json mcp-task-orchestrator` running `docker run --rm -i` with the image `ghcr.io/jpicklyk/task-orchestrator:latest`, or a block in `.mcp.json`. Docker must be running.
What does server-side enforcement mean?
The server blocks a transition when a required note is missing or a dependency is unfinished and names the reason. Reminders in the prompt do not help the agent.
Where are the rules set?
In `.taskorchestrator/config.yaml` in the project, mounted into the container. The Claude Code plugin adds the `/task-orchestrator:manage-schemas` skill.
How do I work across several repositories?
Run one persistent server in HTTP mode and the plugin's `config-sync` hook pushes each project's config into it. The port is published only on `127.0.0.1`.
Is the Claude Code plugin required?
No, the server works with any MCP client. The plugin adds skills and hooks on top of it.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server that turns GitHub Projects v2 into a work queue for agents: they claim tasks, report progress and spend a budget.
An MCP server that lets an agent read files, search code and run commands in a workspace
A plugin with skills for building TypeScript MCP servers and MCP apps: the agent scaffolds, edits, debugs and verifies them
add-mcp writes an MCP server into the configs of 25 agents with one command: Claude Code, Codex, Cursor, VS Code, Zed and more
A transparent proxy between an AI client and an MCP server: shows every JSON-RPC frame in the terminal, checks a capture in CI and exports spans
An MCP server that builds a code graph once and serves the answer to the agent instead of re-reading files
README in short
The text explains the problem of multi-agent workflows, shows a new session's morning with `items_read`, `advance` and `notes_write` calls, gives three install options and describes the phase model.