MCP Server
Swarm ships an MCP (Model Context Protocol) server that connects directly to your AI coding editor. Instead of switching to a browser or terminal, you can test your app from inside Claude Code or Cursor with a single command.
How it works
You (in Claude Code) → "test my signup flow"
↓
Claude calls dev_test → tunnels localhost → runs AI agents
↓
Claude calls dev_watch → gets structured issues
↓
Claude fixes the code → calls dev_test again
Install
One command adds Swarm MCP to Claude Code:
This registers the MCP server with Claude Code. On first use, your browser opens to log in automatically.
Manual setup
If you prefer to configure it yourself:
claude mcp add useswarm -- npx @useswarm/mcp
Other editors
For Cursor or any MCP-compatible editor, add to your MCP config:
{
"mcpServers": {
"useswarm": {
"command": "npx",
"args": ["@useswarm/mcp"]
}
}
}
Authentication
The MCP server uses API keys scoped to your Swarm account. Authentication is handled automatically:
- First use — browser opens to log you in, API key is created and stored at
~/.useswarm/config.json
- Subsequent uses — stored key is used automatically
You can also manage auth manually:
npx @useswarm/mcp login # Log in via browser
npx @useswarm/mcp logout # Clear stored credentials
npx @useswarm/mcp whoami # Check auth status
Tools
The MCP server exposes 4 tools that form a test-fix-retest loop:
dev_test
Tunnel your localhost and start an AI agent swarm test.
Parameters:
| Parameter | Required | Description |
|---|
targetUrl | Yes | Frontend URL (e.g. http://localhost:3000) |
goal | Yes | What agents should accomplish (e.g. “complete the signup flow”) |
userDescription | Yes | Target audience (e.g. “first-time SaaS users”) |
agentCount | No | Number of AI personas (1-20, default 3) |
backendUrl | No | Separate backend URL (e.g. http://localhost:8080) |
backendPaths | No | Extra path prefixes for backend routing (e.g. ["/ws", "/v1"]) |
auth | No | Login credentials for authenticated testing |
Use dev_test to test http://localhost:3000 with goal “sign up and reach the dashboard”. The audience is first-time users.
dev_watch
Poll a running test until it completes, then return structured results.
Parameters:
| Parameter | Required | Description |
|---|
batchId | Yes | Batch ID returned by dev_test |
wait | No | Poll up to 3 minutes for completion (default true) |
dev_status
Check the current state of the tunnel and any active test.
dev_close
Manually tear down the active tunnel and clean up.
Split frontend/backend
If your app runs the frontend and backend on separate ports, pass backendUrl and the MCP server starts a reverse proxy automatically:
Use dev_test to test http://localhost:3000 with backend at http://localhost:8080. Goal: “create a new project”.
The proxy routes by path prefix:
| Path | Destination |
|---|
/api/* | Backend |
/auth/* | Backend |
/graphql | Backend |
/trpc/* | Backend |
| Everything else | Frontend |
Custom API paths
If your backend uses non-standard paths, pass backendPaths:
Test http://localhost:3000 with backend http://localhost:8080 and extra backend paths /ws and /socket.io. Goal: “send a message in the chat”.
Authenticated testing
Pass login credentials to test flows behind a login page:
Use dev_test on http://localhost:3000 with goal “edit profile settings”. Auth: username test@example.com, password testpass123, login URL http://localhost:3000/login.
Use test-only accounts. Credentials are sent to the Swarm API over HTTPS but should not be production credentials.
The dev loop
The MCP server is designed for an iterative test-fix-retest workflow:
- Make a code change
- Ask Claude to run
dev_test
- Ask Claude to run
dev_watch for results
- Claude reads the issues and fixes the code
- Repeat from step 2
Claude handles the full loop automatically. A typical prompt:
Test my app at localhost:3000. The goal is “complete the checkout flow”. If there are issues, fix them and re-test until it passes.
Tunnel providers
The MCP server uses Cloudflare Quick Tunnels by default (free, no account needed). Falls back to ngrok if Cloudflare is unavailable.
Install Cloudflare for the best experience:
# macOS
brew install cloudflared
# Linux
curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
-o /usr/local/bin/cloudflared && chmod +x /usr/local/bin/cloudflared
Framework notes
| Framework | Notes |
|---|
| Next.js / Nuxt / Remix | Single port — no backendUrl needed |
| React + Express | Use backendUrl for the Express server |
| Django / Rails | Add the tunnel URL to ALLOWED_HOSTS / CORS config |
| Vite with proxy | If Vite proxies API calls, no backendUrl needed |
