@useswarm/mcp

Useswarm MCP Server

Connect the Useswarm UX testing platform to AI agents (Claude Code, Cursor, VS Code, etc.) via the Model Context Protocol.

Local Machine                          mcp.useswarm.co
+--------------------+    WebSocket    +--------------------+
|  useswarm-mcp      |<---tunnel----->|  Relay Server      |
|  (MCP Server)      |                |  /tunnel (WS)      |
|                    |                |  /s/:slug/message   |
|  27 tools -> API   |                +--------------------+
+--------------------+                        ^
        ^                              Remote MCP Clients
        |                              (Claude Code, Cursor)
   stdio / HTTP
        |
  Local MCP Client

Quick Start

# 1. Log in via browser (creates an API key, stores in ~/.useswarm/config.json)
npx @ux-testing/mcp-server login

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

That's it. Claude Code can now create tests, run persona agents, analyze results, and more.

Installation

Option A: npx (recommended)

No installation needed. Just run:

npx @ux-testing/mcp-server login
npx @ux-testing/mcp-server serve

Option B: From source (contributors)

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

Option C: With tunnel (remote access)

Tunnel your local MCP server through mcp.useswarm.co so remote clients can connect without port forwarding:

npx @ux-testing/mcp-server serve --tunnel --tunnel-token YOUR_TOKEN

The CLI prints your public endpoint:

[useswarm-mcp] Public MCP endpoint: https://mcp.useswarm.co/s/abc123/message
[useswarm-mcp] Add to Claude Code:
  claude mcp add useswarm --transport streamable-http https://mcp.useswarm.co/s/abc123/message

CLI Commands

Command	Description
useswarm-mcp login	Open browser to useswarm.co, create MCP API key, store locally
useswarm-mcp logout	Clear stored credentials from ~/.useswarm/config.json
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 HTTP transport on port 3100
useswarm-mcp serve --tunnel	Start with 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

Available Tools

Batch Tests

Run autonomous AI personas against a website to get UX feedback.

Tool	Description
list_batch_tests	List all batch test runs
get_batch_test	Get details of a specific test
create_batch_test	Create a new batch test with AI personas
run_batch_test	Start executing a batch test
cancel_batch_test	Cancel a running test
get_batch_test_results	Get aggregated results and insights
generate_personas	Generate personas from an audience description
delete_batch_test	Delete a test and its results

Screenshot Tests

Upload screenshots of a user flow and get AI persona analysis.

Tool	Description
create_screenshot_test	Create a screenshot-based test
analyze_screenshot_test	Run persona analysis on uploaded screenshots
get_screenshot_test_results	Get analysis results and insights
generate_mockups	Generate improved UI mockups from findings

UX Agent

Interact with autonomous agent runs.

Tool	Description
get_queue_status	Check job queue depth and worker status
get_agent_run	Get details of an agent run
get_agent_thoughts	Get structured thoughts from a run
get_agent_insights	Get AI-generated insights
chat_with_persona	Ask follow-up questions to a persona

Scout AI

Deep research and analysis across test results.

Tool	Description
scout_chat	Chat with Scout about test findings
scout_history	Get chat history and suggested questions

Swarms

Manage reusable groups of personas.

Tool	Description
list_swarms	List all persona swarms
create_swarm	Create a new persona swarm
get_swarm	Get swarm details and personas
delete_swarm	Delete a swarm

Projects

Organize tests into projects.

Tool	Description
list_projects	List all projects
create_project	Create a new project
get_project	Get project details

Device Farm

Test mobile apps on real devices via AWS Device Farm.

Tool	Description
enqueue_mobile_test	Enqueue a mobile app test job
get_mobile_test_job	Get mobile test status and results
list_devices	List available real devices

CUA Tests

Run Computer Use API tests with autonomous visual agents.

Tool	Description
run_cua_test	Run a CUA test against a URL
get_cua_test	Get CUA test results

Editor Configuration

Claude Code

claude mcp add useswarm -- npx @ux-testing/mcp-server serve

Cursor

Add to .cursor/mcp.json:

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

VS Code (Copilot)

Add to .vscode/settings.json:

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

Remote via tunnel (any editor)

If you're using the tunnel, configure the editor with the HTTP transport:

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

Authentication

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

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 set the environment variable:

export USESWARM_API_KEY=ux_your_key_here
useswarm-mcp serve

Environment Variables

Variable	Default	Description
USESWARM_API_URL	http://localhost:8080	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 (for 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

Architecture

Transports

The MCP server supports three transport modes:

• stdio (default) -- Standard input/output. Used by Claude Code, Cursor, etc. 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 requests through the tunnel.

Relay Server

The relay server runs at mcp.useswarm.co and 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
# Edit terraform.tfvars with your ACM cert ARN, VPC tags, etc.
terraform init
terraform plan
terraform apply

Development

# Run MCP server in dev mode (auto-reload)
pnpm dev

# Run relay server locally
pnpm start:relay

# Type-check
npx tsc --noEmit

# Build
pnpm build

URLs

Service	URL
Web app	https://useswarm.co
API	https://api.useswarm.co
MCP relay	https://mcp.useswarm.co