@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 registers the MCP with Claude Code + Codex CLI and signs you in:

npx @useswarm/mcp@latest setup

After it finishes, open your editor and ask it to test your app:

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

[!NOTE] Login happens in your terminal as part of setup — not on first use inside the editor. If the MCP starts without a key, it exits with a clear message telling you to run setup or login again.

Updating

npx @useswarm/mcp@latest setup

Same command — @latest pulls the newest npm release and rewrites the path in your editor's config so the next launch picks it up. Restart the editor afterwards.

Installation

Option A: npx (recommended)

npx @useswarm/mcp@latest setup                  # registers all hosts + signs in
npx @useswarm/mcp@latest setup --client claude  # Claude Code only
npx @useswarm/mcp@latest setup --client codex   # Codex CLI only
npx @useswarm/mcp@latest setup --skip-login     # register only (use env-based keys)

Option B: Global install (stable path, easy upgrades)

npm install -g @useswarm/mcp
useswarm-mcp setup
# upgrade later:
npm update -g @useswarm/mcp
# no re-setup needed — the global path is stable

Option C: Manual setup

# Claude Code
claude mcp add useswarm -- npx @useswarm/mcp
npx @useswarm/mcp login   # one-time, in a terminal

# Codex CLI — add to ~/.codex/config.toml
#   [mcp_servers.useswarm]
#   command = "npx"
#   args = ["@useswarm/mcp"]
npx @useswarm/mcp login

Option D: From source (contributors)

cd apps/mcp-server
pnpm install
pnpm build
node dist/cli.js setup --client codex   # or --client claude

See CODEX_TESTING.md for the local-build iteration loop.

CLI commands

Command	Description
useswarm-mcp setup	Register MCP with Claude Code + Codex CLI, then sign in (one-shot setup)
useswarm-mcp setup --skip-login	Register only — for CI / env-key workflows
useswarm-mcp login	Open browser to sign in; stores API key at ~/.useswarm/config.json
useswarm-mcp logout	Clear stored credentials
useswarm-mcp whoami	Show auth status and verify the stored key still works
useswarm-mcp serve	Start MCP server (stdio, default). Refuses to start if no key — won't auto-login.
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 for this process
useswarm-mcp serve --api-url URL	Override API base URL

Tools

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

dev_list_swarms

List the saved persona swarms tied to the user's account (personal + active org). Use this to discover swarm IDs before passing one to dev_test.

Returns { swarms: Array<{ id, name, description, agentCount, personaCount, createdAt }>, count }.

Use dev_list_swarms to show me which Useswarm persona sets are saved on my account.

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")
swarmId	Conditional	UUID of a saved swarm (from dev_list_swarms). When set, runs that swarm's stored personas instead of generating new ones. Mutually exclusive with userDescription/agentCount.
userDescription	Conditional	Target audience (e.g. "first-time SaaS users"). Required when swarmId is not set.
agentCount	No	Number of AI personas to generate (1–20, default 3). Ignored when swarmId is set.
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.

Use dev_list_swarms, then dev_test on http://localhost:3000 with goal "complete checkout" using my "B2B Buyers" swarm.

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

Codex CLI

npx @useswarm/mcp setup --client codex

This writes a [mcp_servers.useswarm] block to ~/.codex/config.toml. Restart Codex and the four tools (dev_test, dev_watch, dev_status, dev_close) will appear. The first dev_test triggers a device-code login if you haven't authenticated yet — the URL + code prints to Codex's stderr.

For testing the local build, iterating on tool definitions, or running Codex cloud, see CODEX_TESTING.md.

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://www.useswarm.co	Web app URL (login flow + dashboard links)
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://www.useswarm.co
API	https://api.useswarm.co
MCP relay	https://mcp.useswarm.co
Docs	https://docs.useswarm.co