@useswarm/mcp

Automated UX testing loop for local development. Connects your AI coding editor (Claude Code, Cursor, VS Code, etc.) to the Useswarm UX testing platform via the Model Context Protocol.

You (in Claude Code) → "test my signup flow"
        ↓
Claude calls dev_test → tunnels localhost → runs AI agent swarm
        ↓
Claude calls dev_watch → gets structured UX issues
        ↓
Claude fixes the code → calls dev_test again

The MCP server runs locally via stdio. No remote server needed. It tunnels your localhost via Cloudflare so Useswarm's cloud agents can reach your dev server.

Quick Start

One command adds Useswarm MCP to Claude Code and auto-logs you in on first use:

npx @useswarm/mcp setup

After that, ask Claude to test your app:

Test localhost:3000 with goal "complete the signup flow". The audience is first-time SaaS users.

Installation

Option A: npx (recommended)

No installation needed:

npx @useswarm/mcp setup

Option B: Manual setup

# 1. Log in (creates an MCP API key, stores at ~/.useswarm/config.json)
npx @useswarm/mcp login

# 2. Add to Claude Code
claude mcp add useswarm -- npx @useswarm/mcp serve

Option C: From source (contributors)

cd apps/mcp-server
pnpm install
cp .env.example .env
# Edit .env with USESWARM_API_KEY
pnpm dev

CLI commands

| Command | Description | |---------|-------------| | useswarm-mcp setup | Add to Claude Code and auto-login on first use | | useswarm-mcp login | Open browser to log in, store API key in ~/.useswarm/config.json | | useswarm-mcp logout | Clear stored credentials | | useswarm-mcp whoami | Show auth status and verify API key | | useswarm-mcp serve | Start MCP server (stdio transport, default) | | useswarm-mcp serve --http | Start with streamable HTTP transport on port 3100 | | useswarm-mcp serve --tunnel | Start with WebSocket tunnel to mcp.useswarm.co | | useswarm-mcp serve --api-key KEY | Override stored API key | | useswarm-mcp serve --api-url URL | Override API base URL |

Tools

The server exposes four tools that form a test-fix-retest loop:

dev_test

Tunnel your localhost (or hit a public URL directly) and start an AI agent swarm test.

| 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 — when set, a reverse proxy routes /api/*, /auth/*, /graphql, /trpc/* to the backend through one tunnel | | backendPaths | No | Extra path prefixes for backend routing (e.g. ["/ws", "/v1"]) | | maxSteps | No | Max steps per agent | | provider | No | openai or anthropic | | model | No | Model override | | auth | No | Login credentials, sub-aliased sign-up, or session cookies — see 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.

| Parameter | Required | Description | |---|---|---| | batchId | Yes | Batch ID returned by dev_test | | wait | No | Poll up to 3 minutes for completion (default true) |

Returns issues sorted by severity with persona attribution, plus a synthesis report. Automatically tears down the tunnel when done.

dev_status

Check the current state of the active tunnel and any running 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 on 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 |

For non-standard backend 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

The auth parameter on dev_test supports three modes. All accept an optional startUrl to land the agent on a specific page after authentication.

Mode 1: agent_login (existing account)

Agent navigates to loginUrl (or the target URL if omitted), fills credentials, submits.

{
  "auth": {
    "mode": "agent_login",
    "loginUrl": "http://localhost:3000/login",
    "username": "[email protected]",
    "password": "testpass123",
    "startUrl": "http://localhost:3000/dashboard"
  }
}

Mode 2: signup (sub-aliased emails per persona)

For testing sign-up flows where no account exists yet. You supply one base email; each persona registers with a unique local+<hash>@domain sub-alias derived from it. All confirmation emails route to your single inbox, but each persona has its own isolated address.

{
  "auth": {
    "mode": "signup",
    "signupEmail": "[email protected]",
    "signupPassword": "optional-shared-password",
    "startUrl": "http://localhost:3000/signup"
  }
}

| Field | Required | Description | |---|---|---| | signupEmail | Yes | Base email. Each persona-run gets a unique local+<base36(timestamp)+random>@domain alias derived from this. | | signupPassword | No | Shared password used on every persona's sign-up form. If omitted, the runtime mints a strong random password per persona-run (not persisted). | | startUrl | No | URL where the sign-up form lives. |

The base email [email protected] becomes [email protected], [email protected], etc. — one per persona. The timestamp half guarantees the alias can never repeat in the future; the random half disambiguates personas spawned in the same millisecond. Generated aliases are persisted to the run record (cua_runs.generated_email) so confirmation emails can be correlated back to a persona later.

Use any provider that supports plus-addressing — Gmail, Fastmail, custom domains all work.

Mode 3: cookie_injection (skip login)

Inject session cookies and have the agent start already authenticated.

{
  "auth": {
    "mode": "cookie_injection",
    "cookies": [
      {
        "name": "session_token",
        "value": "abc123...",
        "domain": ".example.com",
        "path": "/",
        "secure": true,
        "httpOnly": true
      }
    ],
    "startUrl": "http://localhost:3000/dashboard"
  }
}

Each cookie needs name, value, domain at minimum; everything else is optional and accepts null. The easiest way to capture cookies is the Cookie-Editor browser extension — Export → JSON.

If mode is omitted, the MCP server infers it:

• cookies array → cookie_injection
• signupEmail → signup
• otherwise → agent_login

When testing localhost, cookie domains captured from a different host are auto-rewritten to match the tunnel; loginUrl and startUrl are also tunneled if they point at localhost.

Use test-only accounts. Credentials and cookies are sent to the Useswarm API over HTTPS but should not be production credentials.

Editor configuration

Claude Code

claude mcp add useswarm -- npx @useswarm/mcp serve

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "useswarm": {
      "command": "npx",
      "args": ["@useswarm/mcp", "serve"],
      "env": {
        "USESWARM_API_KEY": "ux_..."
      }
    }
  }
}

VS Code (Copilot)

Add to .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "useswarm": {
        "command": "npx",
        "args": ["@useswarm/mcp", "serve"],
        "env": {
          "USESWARM_API_KEY": "ux_..."
        }
      }
    }
  }
}

Remote via tunnel

If you're running with --tunnel, configure the editor with the streamable HTTP transport:

{
  "mcpServers": {
    "useswarm": {
      "transport": "streamable-http",
      "url": "https://mcp.useswarm.co/s/YOUR_SLUG/message"
    }
  }
}

Authentication (to the MCP server itself)

The MCP server uses X-API-Key header authentication. Keys are SHA-256 hashed before storage server-side.

Browser login (recommended)

useswarm-mcp login

Opens your browser to useswarm.co/mcp/auth. After logging in, an MCP-scoped API key is created and stored in ~/.useswarm/config.json (file permissions: 0600).

Manual API key

Create a key in the Useswarm dashboard or pass one directly:

useswarm-mcp serve --api-key ux_your_key_here

Or via env:

export USESWARM_API_KEY=ux_your_key_here
useswarm-mcp serve

Environment variables

| Variable | Default | Description | |---|---|---| | USESWARM_API_URL | https://api.useswarm.co | API base URL | | USESWARM_API_KEY | — | API key for authentication | | USESWARM_SESSION_TOKEN | — | Session token (alternative to API key) | | USESWARM_APP_URL | https://useswarm.co | Web app URL (login flow) | | MCP_PORT | 3100 | HTTP transport port | | MCP_TUNNEL | false | Enable tunnel to relay | | MCP_TUNNEL_TOKEN | — | Tunnel authentication token | | MCP_RELAY_URL | wss://mcp.useswarm.co | Tunnel relay WebSocket URL |

The dev loop

The server is designed for an iterative test-fix-retest workflow:

1. Make a code change
2. Ask Claude to run dev_test
3. Ask Claude to run dev_watch for results
4. Claude reads the issues and fixes the code
5. Repeat

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.

Architecture

Transports

1. stdio (default) — used by Claude Code, Cursor, VS Code. No network port needed.
2. HTTP (--http) — streamable HTTP on port 3100. For clients that prefer HTTP transport.
3. Tunnel (--tunnel) — connects via WebSocket to the relay at mcp.useswarm.co. The relay assigns a public slug and proxies JSON-RPC through the tunnel.

Relay server

The relay at mcp.useswarm.co handles:

• WebSocket tunnel connections from local MCP servers (/tunnel)
• Public HTTP endpoints for remote MCP clients (/s/:slug/message)
• Token-based tunnel authentication with stable slug persistence on reconnect
• 2-minute request timeout, 30-second keep-alive pings

Infrastructure

The relay is deployed on AWS ECS Fargate. See infra/ for the Terraform configuration:

cd apps/mcp-server/infra
cp terraform.tfvars.example terraform.tfvars
terraform init
terraform plan
terraform apply

Tunnel providers

The MCP server uses Cloudflare Quick Tunnels by default (free, no account needed) and 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 / config.hosts | | Vite with proxy | If Vite proxies API calls, no backendUrl needed |

Development

pnpm dev              # MCP server in dev mode (auto-reload)
pnpm start:relay      # Relay server locally
npx tsc --noEmit      # Type-check
pnpm build            # Build

URLs

| Service | URL | |---|---| | Web app | https://useswarm.co | | API | https://api.useswarm.co | | MCP relay | https://mcp.useswarm.co | | Docs | https://docs.useswarm.co |