MCP Task Orchestrator

What MCP Task Orchestrator MCP server does

MCP Task Orchestrator MCP server coordinates AI coding work through persistent work items, dependencies, workflow phases, notes, and actor records. It is designed for multi-agent and multi-session development, including an orchestrator dispatching sub-agents, a new session resuming unfinished work, or an autonomous process working through a backlog.

Each item has a role such as queue, work, review, blocked, or terminal. Agents do not directly edit the status. They request a transition with advance_item, and the server checks the applicable rules before applying it. Upstream dependencies can prevent an item from progressing, while required documentation can prevent it from leaving a phase.

How it works

The server stores workflow state in a persistent SQLite database. get_context provides current items, recent transitions, blocking information, and ancestor chains so a new session can recover project state without replaying an earlier conversation. advance_item records the actor and evaluates dependency and documentation gates. manage_notes creates or updates the notes that a schema requires for a particular phase.

Workflow schemas are written in YAML and associate note requirements with roles. For example, a schema can require a requirements note before an item leaves the queue phase. If that note is absent, the transition fails with an explanation of the missing requirement. Schemas can also define a planning floor that specifies documentation needed before implementation begins.

The server supports a per-session STDIO container and a persistent HTTP deployment. The HTTP approach is intended for multiple projects and can receive project configuration through the plugin's config-sync hook. Configuration changes can be reloaded without restarting that deployment.

Setup and configuration

Docker is the documented prerequisite. A basic setup registers the ghcr.io/jpicklyk/task-orchestrator:latest image as an MCP STDIO server and mounts a named volume at /app/data. On first startup, the server creates its SQLite database. Without a configuration file, tools operate in schema-free mode, so no gates or required notes are enforced.

To enable enforcement, create .taskorchestrator/config.yaml and mount that directory into the container. Set AGENT_CONFIG_DIR to the mounted project location. The documented setup exposes only the .taskorchestrator/ directory to the container, not the rest of the project.

For a shared persistent process, enable HTTP transport and the REST API, publish the service on a loopback address, and register the MCP endpoint at /mcp. Projects can point the configuration-sync hook to the service with TASK_ORCHESTRATOR_API_URL.

Tools and capabilities

• Recover current workflow state and recent activity with get_context.
• Move work items through validated phase transitions with advance_item.
• Add or update phase documentation with manage_notes.
• Enforce dependency ordering across a work breakdown.
• Record the actor responsible for transitions and notes.
• Apply YAML-defined requirements instead of prompt-only conventions.

Limitations and notes

MCP Task Orchestrator MCP server does not enforce gates when no schema is configured. HTTP deployments using unauthenticated REST provide full read, write, and delete access to anyone who can reach the port; the documented unauthenticated example is therefore restricted to 127.0.0.1. Networked or shared deployments should use bearer-token or JWKS authentication.

The Docker configuration requires absolute host paths for mounted project configuration. In Claude Code's .mcp.json, ${VAR} and ${VAR:-default} environment expansion is supported, but editor placeholders such as ${workspaceFolder} are not substituted. A Claude Code plugin is available as an optional layer that adds skills and hooks, but the MCP server can also be used directly by MCP clients.