TaskPeace: Task Queue Plumbing for MCP-Based Agent Work Distribution

TaskPeace is a task queue built for AI coding agents that pull work over MCP (Model Context Protocol). The project surfaces a specific infrastructure problem: how do you coordinate multiple agents working from a shared queue without building a centralized orchestrator? The answer involves queue semantics that fit MCP’s request-response model, state transitions that handle non-deterministic agent execution, and a clear boundary between what the queue owns (work distribution, claiming, timeouts) and what the agent owns (execution, tool calls, error recovery).

Why a Queue Instead of Direct Orchestration

Most agent frameworks use direct orchestration: a controller assigns tasks, monitors execution, and handles failures. TaskPeace inverts this. Agents pull work when ready. The queue tracks state but does not execute logic. This pattern decouples agent availability from task creation and lets you scale agents horizontally without changing the queue.

The trade-off is visibility. With direct orchestration, you know which agent is doing what. With a queue, you know which task is claimed but not which agent instance holds it unless you add agent identity tracking.

MCP as the Work Distribution Protocol

MCP is a context protocol, not a message queue protocol. It defines how agents request tools, resources, and prompts from servers. TaskPeace exposes the queue as an MCP server with three tools:

get_next_task: Returns the highest-priority unclaimed task plus context (description, dependencies, project metadata).
complete_task: Marks a task done and logs the result.
update_task: Lets agents modify task state mid-execution (useful for long-running work or handoffs).

This maps queue operations onto MCP’s request-response model. An agent calls get_next_task, receives a task payload, does the work using its own tools, then calls complete_task. The queue does not see the agent’s internal tool calls or execution flow.

Task Claiming and State Transitions

A task moves through these states:

State	Meaning	Transitions To
`open`	Available for claiming	`in_progress`, `blocked`
`in_progress`	Claimed by an agent	`done`, `failed`, `open`
`blocked`	Waiting on a dependency or external event	`open`, `failed`
`done`	Completed successfully	(terminal)
`failed`	Agent reported failure or timeout expired	`open` (if retryable), (terminal)

When an agent calls get_next_task, the queue atomically moves the task from open to in_progress and attaches a claim timestamp. If the agent does not call complete_task or update_task within a timeout window (default 30 minutes), the queue transitions the task back to open and makes it available for another agent.

This timeout-based reclaim handles silent agent failures (network partition, crash, infinite loop). It does not handle partial work. If an agent writes half a file and times out, the next agent sees the task as fresh. You need idempotent task design or external state tracking to avoid duplicate work.

The Orchestration Boundary

TaskPeace owns:

Work distribution (which task is next based on priority and dependencies).
Claim semantics (atomic transitions, timeout enforcement).
State tracking (task history, completion logs).

The agent owns:

Execution strategy (which tools to call, in what order).
Error recovery (retry logic, fallback paths).
Tool orchestration (calling file system tools, Git commands, API clients).

This boundary matters because it determines where complexity lives. The queue does not know what “refactor the auth middleware” means. It just knows the task is open, has priority 3, and depends on task 42 being done. The agent decides whether to use grep, sed, an AST parser, or an LLM to do the refactoring.

If you need the queue to enforce execution constraints (e.g., “only run this task on agents with GPU access”), you must add agent capability metadata and filter tasks in get_next_task. TaskPeace does not ship this. You would implement it as a custom MCP server extension.

Failure Modes and Observability

Silent claim expiration: An agent claims a task, starts work, then loses network. The task times out and another agent claims it. You now have two agents working the same task. Mitigation: make tasks idempotent or add agent heartbeat calls to update_task.

Priority inversion: A high-priority task depends on a low-priority task. If agents always pull the top task, the low-priority dependency never gets claimed. Mitigation: the queue must promote dependency tasks or agents must check dependencies before claiming.

Claim starvation: If tasks timeout and return to open, a failing task can block the queue by repeatedly claiming and timing out. Mitigation: add a retry counter and move tasks to failed after N attempts.

Observability gaps: The queue logs task state transitions but does not see agent tool calls. If an agent claims a task and hangs inside a tool call, you see in_progress but no detail. Mitigation: agents must log tool calls to an external observability system (structured logs, traces, or a separate MCP logging server).

Deployment Shape

TaskPeace runs as:

MCP server: Agents connect via stdio (local) or HTTP (remote). The server exposes get_next_task, complete_task, update_task as MCP tools.
Web UI: A React app that reads the same task database and renders the queue, task history, and agent activity.
Database: SQLite for local deployments, Postgres for multi-agent or multi-user setups.

For a single developer with one agent, you run the MCP server locally and the agent connects via stdio. For a team with multiple agents, you deploy the server to a VM or container, expose it over HTTPS, and configure agents with an API key.

The MCP server is stateless except for the database connection. You can run multiple server instances behind a load balancer if you use Postgres with row-level locking for atomic task claims.

Code: Atomic Task Claim

Here is how get_next_task atomically claims a task in Postgres:

WITH next_task AS (
  SELECT id
  FROM tasks
  WHERE status = 'open'
    AND (depends_on IS NULL OR depends_on IN (
      SELECT id FROM tasks WHERE status = 'done'
    ))
  ORDER BY priority DESC, created_at ASC
  LIMIT 1
  FOR UPDATE SKIP LOCKED
)
UPDATE tasks
SET status = 'in_progress',
    claimed_at = NOW(),
    claimed_by = $1
WHERE id = (SELECT id FROM next_task)
RETURNING id, title, description, priority, context;

FOR UPDATE SKIP LOCKED prevents two agents from claiming the same task. If agent A locks row 5, agent B’s query skips row 5 and claims row 6. The dependency check ensures tasks only become claimable after their dependencies are done.

When to Use TaskPeace

Use it when:

You have multiple agents (or multiple instances of the same agent) working from a shared backlog.
You want agents to pull work autonomously instead of waiting for a controller to assign tasks.
You need task prioritization and dependency tracking without building a custom orchestrator.
Your agents already support MCP and you want a standard interface for work distribution.

Avoid it when:

You need real-time task assignment based on agent capabilities (GPU, API keys, location). TaskPeace does not filter tasks by agent metadata.
You need visibility into agent execution internals (tool calls, intermediate state). The queue only sees claim and completion events.
Your tasks are not idempotent and you cannot tolerate duplicate execution after a timeout.
You need sub-second task latency. The queue uses polling (agents call get_next_task every N seconds) rather than push-based distribution.

Technical Verdict

TaskPeace is useful infrastructure for teams running multiple coding agents over MCP. It solves work distribution without requiring a centralized orchestrator, and the queue semantics (atomic claims, timeout-based reclaim, dependency tracking) handle the common failure modes of agent-based execution. The main limitation is observability: you see task state but not agent execution detail. If you need deep visibility, pair this with structured logging or a separate tracing system. If you need capability-based task routing or sub-second latency, you will need to extend the MCP server or use a different distribution pattern.

Agentic AI, minus the noise.