@useswarm/mcp

@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": "[e-mail]",
    "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": "[e-mail]",
    "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 [e-mail] becomes [e-mail], [e-mail], 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:

• 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

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

• stdio (default) — used by Claude Code, Cursor, VS Code. No network port needed.
• HTTP (--http) — streamable HTTP on port 3100. For clients that prefer HTTP transport.
• 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