Skip to main content

Setting Up Multi-Agent Workflows with MCP in Cursor

Cursor MCP Multi-Agent

As projects grow in complexity, a single AI agent may not be enough. Cursor supports multi-agent workflows through MCP (Model Context Protocol) servers, allowing multiple specialized agents to collaborate on different aspects of your project simultaneously. This guide shows you how to set up and coordinate multiple agents effectively.

What is Multi-Agent Coordination?​

Multi-agent coordination allows you to:

  • Split complex tasks across specialized agents (e.g., one for frontend, one for backend)
  • Work in parallel on different parts of your codebase
  • Maintain separation of concerns with dedicated agents for specific domains
  • Scale your AI assistance as your project grows

Prerequisites​

Before setting up multi-agent workflows:

  1. Cursor Pro or higher - Multi-agent features require a paid plan
  2. MCP server support - Ensure MCP is enabled in your Cursor settings
  3. Git repository - Multi-agent workflows work best with version control

Setting Up Worktree Configuration​

The .cursor/worktrees.json file is the key to multi-agent coordination.

Step 1: Create the Configuration File​

Create .cursor/worktrees.json in your project root:

{
  "worktrees": [
    {
      "id": "frontend-agent",
      "name": "Frontend Agent",
      "description": "Handles UI components, styling, and client-side logic",
      "directories": ["src/components", "src/pages", "src/styles", "public"],
      "rules": [
        "Use React and TypeScript",
        "Follow the existing component patterns",
        "Use Tailwind CSS for styling",
        "Ensure responsive design"
      ]
    },
    {
      "id": "backend-agent",
      "name": "Backend Agent",
      "description": "Manages API endpoints, database models, and server logic",
      "directories": ["src/api", "src/models", "src/middleware", "migrations"],
      "rules": [
        "Use Express.js with TypeScript",
        "Follow RESTful conventions",
        "Implement proper error handling",
        "Add input validation"
      ]
    },
    {
      "id": "test-agent",
      "name": "Testing Agent",
      "description": "Writes and maintains test suites",
      "directories": ["tests", "src/__tests__", "cypress"],
      "rules": [
        "Use Jest for unit tests",
        "Use React Testing Library for component tests",
        "Aim for 80%+ coverage",
        "Write integration tests for API endpoints"
      ]
    }
  ]
}

Step 2: Configure MCP Servers​

Add MCP servers to your Cursor settings (Cmd/Ctrl + Shift + P → "Cursor Settings"):

{
  "mcpServers": {
    "task-coordinator": {
      "command": "npx",
      "args": ["-y", "@cursor-task/coordinator"],
      "env": {
        "WORKTREE_CONFIG": "./.cursor/worktrees.json"
      }
    },
    "file-sync": {
      "command": "npx",
      "args": ["-y", "@cursor-task/file-sync"]
    }
  }
}

Using Multi-Agent Mode​

Starting a Multi-Agent Session​

  1. Open Composer (Cmd/Ctrl + I)
  2. Click the agent selector (top of Composer)
  3. Select "Multi-Agent" mode
  4. Choose which agents to activate

Task Assignment​

Agents automatically pick up tasks based on the files you reference:

@src/components/UserProfile.tsx @src/api/users.ts 

Implement a user profile page that fetches data from the API and displays it. 
The frontend agent should handle the UI, and the backend agent should ensure the API endpoint returns the correct data.

Manual Task Routing​

You can also direct tasks to specific agents:

[@frontend-agent] Create a responsive navigation component with mobile hamburger menu

[@backend-agent] Add a /api/navigation endpoint that returns menu items based on user role

Communication Between Agents​

Agents communicate through a shared task file system.

Task Files​

Tasks are tracked in .cursor/tasks/:

.cursor/
  tasks/
    TASK-001-frontend-nav.md
    TASK-002-backend-api.md
    TASK-003-integration-test.md

Each task file contains:

# TASK-001: Navigation Component

## Status: IN_PROGRESS
## Assigned: frontend-agent
## Dependencies: None

## Description
Create a responsive navigation component...

## Acceptance Criteria
- [ ] Mobile hamburger menu works
- [ ] Desktop horizontal layout
- [ ] Active state highlighting

## Notes
- Use the existing Button component
- Follow the design in Figma (link)

Agent Handoffs​

When one agent completes a task that another depends on:

## Handoff Notes

Completed by: frontend-agent
Handed to: test-agent

The Navigation component is in src/components/Navigation.tsx.
Props interface is defined. Ready for testing.

Best Practices for Multi-Agent Workflows​

1. Define Clear Boundaries​

Each agent should have a well-defined scope:

{
  "id": "database-agent",
  "directories": ["src/db", "migrations", "seeds"],
  "rules": [
    "Only modify files in the assigned directories",
    "Run migrations before committing changes",
    "Document schema changes in CHANGELOG.md"
  ]
}

2. Use Shared Contracts​

Define interfaces that agents agree on:

// src/types/shared.ts
// This file is read by ALL agents

export interface ApiResponse<T> {
  data: T;
  success: boolean;
  error?: string;
}

export interface User {
  id: string;
  email: string;
  name: string;
  role: 'admin' | 'user';
}

3. Implement Conflict Resolution​

When agents modify the same files:

{
  "conflictResolution": {
    "strategy": "last-write-wins",
    "notification": true,
    "manualReview": ["src/types/shared.ts", "package.json"]
  }
}

4. Monitor Agent Activity​

Track what each agent is doing:

# View active tasks
cat .cursor/tasks/*.md | grep "Status: IN_PROGRESS"

# Check recent agent commits
git log --oneline --all --grep="agent:" | head -20

Example: Full Multi-Agent Workflow​

Let's build a feature with three agents working together:

Phase 1: Backend Agent​

[@backend-agent] Create a /api/products endpoint with CRUD operations.
Use the existing database connection in src/db/index.ts.
Follow the ApiResponse interface in src/types/shared.ts.

Phase 2: Frontend Agent (starts after backend commits)​

[@frontend-agent] Create a ProductList component that fetches from /api/products.
Use React Query for data fetching.
Display products in a responsive grid.

Phase 3: Test Agent (starts after frontend commits)​

[@test-agent] Write tests for the ProductList component and /api/products endpoint.
Include error state tests.
Aim for 85%+ coverage.

Troubleshooting Multi-Agent Issues​

IssueSolution
Agents overwrite each other's changesDefine stricter directory boundaries in worktrees.json
Tasks not being picked upCheck that task files are in .cursor/tasks/ with correct status
Agents conflicting on shared filesAdd files to manualReview in conflictResolution
One agent is idleEnsure task dependencies are marked as completed

Advanced: Custom MCP Servers​

For specialized workflows, create custom MCP servers:

// mcp-server-custom.js
const { Server } = require('@modelcontextprotocol/sdk/server/index.js');

const server = new Server({
  name: 'custom-task-router',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {}
  }
});

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'route-task') {
    const { task, agentPool } = request.params.arguments;
    // Custom routing logic
    const bestAgent = selectBestAgent(task, agentPool);
    return {
      content: [{
        type: 'text',
        text: `Task routed to ${bestAgent}`
      }]
    };
  }
});