Cursor setup

Switchman works natively with Cursor via MCP. Set up once and Cursor agents coordinate automatically across all your workspaces.

ℹ

Prerequisites: Complete Getting started first. Cursor works with the normal Switchman workspace flow, whether that came from switchman start or manual switchman setup --agents N.

How Cursor MCP works

Switchman setup automatically creates a .cursor/mcp.json file in your repo root and in each agent workspace. Cursor reads this file and makes the Switchman MCP tools available in the agent sidebar.

✓

Unlike some MCP integrations, Switchman's Cursor config requires no API keys or manual configuration. The .cursor/mcp.json file is self-contained.

Step 1 — Create your agent workspaces

cd my-project
switchman setup --agents 5
switchman verify-setup

This writes .cursor/mcp.json into the repo root and each generated workspace.

Step 2 — Verify MCP config

cat .cursor/mcp.json

You should see a config pointing to the switchman-mcp binary. If the file is missing, run switchman setup again.

Step 3 — Open workspaces in Cursor

Open each agent workspace as a separate Cursor window:

cursor ../my-project-agent1
cursor ../my-project-agent2
cursor ../my-project-agent3

⚠

Each workspace must be opened as its own Cursor project — not as a subfolder. Each workspace has its own .cursor/mcp.json connecting to the shared coordination database in the main repo.

Step 4 — Enable MCP in Cursor settings

In each Cursor window:

Open Settings → Features → MCP
Confirm Switchman appears in the MCP servers list
Toggle it on if it's not already enabled

You should see these tools available in the Cursor agent panel:

switchman_task_next
switchman_task_claim
switchman_task_done
switchman_write_file
switchman_status

Step 5 — Add tasks and start agents

switchman task add "Fix the login bug" --priority 8
switchman task add "Add rate limiting" --priority 6
switchman task add "Update README" --priority 2

Tell each Cursor agent to start working. A short prompt that works well is:

cursor agent promptUse the Switchman MCP tools for coordination.
Get your next task, claim files before editing them, and check CLAUDE.md for repo instructions.

Step 6 — Watch the dashboard

switchman status --watch

This shows all agents, their active tasks, file claims, and any blocked collision attempts in real time.

Troubleshooting

MCP tools not showing in Cursor

Check the config file exists:

ls .cursor/mcp.json

If missing, re-run switchman setup --agents 3. Also check Cursor's MCP settings — some versions require restarting Cursor after a new MCP server is added.

Agent gets "task already claimed"

Another agent claimed that task. The agent should call switchman_task_next again to get a different task. Tasks are dequeued atomically — no two agents can get the same task.

Cursor agent isn't using Switchman tools

Include explicit instructions in your prompt. Cursor agents don't always use MCP tools unless asked. Use the prompt template above or add coordination instructions to a CLAUDE.md file (Cursor reads it too).