Multi-agent coordination

info

This page explains the multi-agent mode with three specialised roles for coordinating complex project work.

MCP Task Server series

1. MCP Task Server
2. Architecture
3. Tools
4. Multi-agent coordination - You are here
5. Project scaffolding

Overview

The server supports three agent roles for coordinating complex projects. Each role has specific permissions that prevent agents from stepping outside their responsibilities.

The three roles

Planner

The Planner creates and organises work but does not execute it.

Can do	Cannot do
Create and organise tasks	Execute tasks
Set dependencies and priorities	Claim tasks
Analyse task complexity	Mark tasks complete
Break down tasks into subtasks
Parse PRDs into task lists

Best for: Project setup, sprint planning, breaking down features into implementable units.

Worker

The Worker claims and executes tasks but cannot create top-level work items.

Can do	Cannot do
Claim and execute tasks	Create top-level tasks
Update progress	Set task priorities
Add subtasks during implementation	Approve or reject work
Mark tasks complete

Best for: Implementation, bug fixes, feature development.

Judge

The Judge reviews completed work and provides quality gates.

Can do	Cannot do
Review completed tasks	Claim or modify tasks
Approve work that meets standards	Execute work
Reject with actionable feedback	Create tasks
Verify acceptance criteria

Best for: Code review, quality assurance, acceptance testing.

When to use multi-agent mode

Use multi-agent mode when

• Working on complex projects with many moving parts
• You want clear separation between planning and execution
• Quality gates are important before work is considered done
• You want to simulate team workflows in AI-assisted development

Use solo mode when

• Working on simple tasks
• Rapid prototyping where speed matters more than process
• You are the only one working on the project
• The task is small enough that role separation adds overhead

Solo mode

Most tasks do not need explicit roles. Solo mode works without specifying agent_id or role:

# Solo mode (no role required)
call add_task({ title: "Build login page" })
call list_tasks
call next_task
call complete_task({ id: "1" })

Multi-agent workflow

For complex projects, explicitly identify agents and their roles:

Step 1: Planner creates tasks

call add_task({ 
  title: "Build authentication system",
  description: "OAuth2 with Google and email/password",
  priority: "high",
  agent_id: "planner-1", 
  role: "planner" 
})

call expand_task({ id: "1" })
# Returns prompt to break into subtasks

call add_subtask({
  parent_id: "1",
  title: "Set up OAuth2 providers",
  agent_id: "planner-1",
  role: "planner"
})

call set_dependencies({ 
  id: "2", 
  dependencies: ["1"],
  agent_id: "planner-1",
  role: "planner"
})

Step 2: Worker claims and executes

call next_task({ agent_id: "worker-1", role: "worker" })
# Returns: Task 1 - Build authentication system

call claim_task({ 
  task_id: "1", 
  agent_id: "worker-1", 
  role: "worker" 
})

# ... implement the feature ...

call update_task({ 
  id: "1", 
  status: "in-progress",
  agent_id: "worker-1",
  role: "worker"
})

# ... complete implementation ...

call complete_task({ 
  id: "1",
  agent_id: "worker-1",
  role: "worker"
})

Step 3: Judge reviews

call review_task({ 
  task_id: "1", 
  agent_id: "judge-1", 
  role: "judge" 
})

# If approved:
call approve_task({ 
  task_id: "1",
  agent_id: "judge-1",
  role: "judge"
})

# If rejected:
call reject_task({ 
  task_id: "1", 
  feedback: "Missing unit tests for edge cases",
  agent_id: "judge-1",
  role: "judge"
})

Step 4: Handle rejection

When work is rejected, it goes back to the Worker:

# Worker sees feedback
call get_task({ id: "1" })
# Shows rejection feedback: "Missing unit tests for edge cases"

# Worker fixes and resubmits
call claim_task({ task_id: "1", agent_id: "worker-1", role: "worker" })
# ... add missing tests ...
call complete_task({ id: "1", agent_id: "worker-1", role: "worker" })

# Judge reviews again
call review_task({ task_id: "1", agent_id: "judge-1", role: "judge" })
call approve_task({ task_id: "1", agent_id: "judge-1", role: "judge" })

Handoff between roles

Use handoff_task to transfer work with context:

# Worker hands off to Judge
call handoff_task({ 
  task_id: "1", 
  to_role: "judge",
  notes: "Implementation complete. All tests passing. Ready for review.",
  agent_id: "worker-1",
  role: "worker"
})

# Judge hands back to Planner after approval
call handoff_task({ 
  task_id: "1", 
  to_role: "planner",
  notes: "Approved. Ready for next phase planning.",
  agent_id: "judge-1",
  role: "judge"
})

Slack notifications

When Slack is configured, handoff_task automatically posts a notification to your Slack channel. This is useful for alerting team members when work is ready for review.

Task lifecycle in multi-agent mode

Best practices

Keep roles consistent

Once an agent claims a role, keep it consistent throughout the session. Switching roles mid-task creates confusion.

Use handoff notes

Always include notes when handing off between roles. Context that seems obvious to you may not be to the next agent.

Start with solo mode

Begin projects in solo mode. Switch to multi-agent when complexity warrants it.

Let the Judge be strict

The Judge role is most valuable when it enforces quality standards consistently. Rubber-stamping approvals defeats the purpose.

Trust the Planner

Let the Planner break down work without Worker intervention. The separation exists so planning can happen thoughtfully before execution begins.