Model Context Protocol

UX testing inside Claude Code, Cursor, and Codex

Swarm’s MCP server gives your AI coding editor a real testing loop. AI personas navigate your localhost dev server, find friction, and feed structured UX issues back into the chat — so the model that wrote the code is the one that sees it break.

Get a free API keyView on GitHub

One command to install

The Swarm MCP server is published to npm as @useswarm/mcp. The setup command registers Swarm with every MCP-capable editor it detects and signs you in.

Install
npx @useswarm/mcp@latest setup

Auto-detects Claude Code and Codex CLI. Add --client claude or --client codex to scope to one. For Cursor and other MCP editors, see the manual config below.

Cursor

Add this to ~/.cursor/mcp.json (or your Cursor MCP settings):

cursor mcp.json
{
  "mcpServers": {
    "useswarm": {
      "command": "npx",
      "args": ["@useswarm/mcp"]
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

codex config.toml
[mcp_servers.useswarm]
command = "npx"
args = ["@useswarm/mcp"]

Then run npx @useswarm/mcp login once to sign in. Credentials are stored at ~/.useswarm/config.json.

How it works

The MCP server runs locally over stdio. It tunnels your localhost through Cloudflare so Swarm’s cloud-hosted AI agents can reach your dev server. No code leaves your machine.

  1. 1

    You prompt your editor

    In Claude Code or Cursor, you write something like "Test localhost:3000 with goal: complete the signup flow. Audience: first-time SaaS users." The model recognizes this as a Swarm tool call and invokes dev_test.

  2. 2

    The MCP tunnels your localhost

    The local MCP server opens a short-lived Cloudflare tunnel so Swarm's cloud-hosted AI agents can reach your dev server. The tunnel closes when the test ends.

  3. 3

    AI personas navigate your app

    Personas matching the audience you described navigate the flow. They click, type, scroll, and read the page like real users — surfacing confusing copy, broken interactions, drop-off points, and missing affordances.

  4. 4

    Structured issues stream back

    Your editor receives a stream of UX findings as they happen. Each finding has a severity, a description, the step it occurred at, and a specific suggested fix. The model can act on them right there.

  5. 5

    Fix, then re-test

    When the model edits code and the dev server reloads, you can re-run the same test with one line. Same audience, same goal — see whether the issues are gone.

The tools your editor gets

Once the MCP is connected, the model can call these as part of its normal tool-use loop. You don’t have to memorize them — just ask the editor to test something.

dev_test

Start a test run. Takes a target URL (usually localhost:3000), a goal in plain English, and an optional audience description.

dev_watch

Stream structured UX issues as the personas find them. Each issue includes a severity, location, and suggested fix.

dev_status

Check progress on an in-flight test — how many personas have run, how many issues found so far.

dev_list_swarms

List the recent test runs for this project. The model uses this to pick up where it left off across sessions.

dev_close

End an active session and tear down the Cloudflare tunnel. Called automatically when a test completes.

What teams use it for

Test the flow you just wrote

After Claude or Cursor writes a new signup, checkout, or onboarding flow, ask it to test the flow it just shipped — before you reload the page yourself.

Catch regressions while iterating

When you refactor, the model can rerun the last test against your dev server and tell you whether anything broke without a full QA cycle.

Validate AI-generated UI

When the model proposes "I changed the CTA copy to X," it can verify that real personas in the target audience actually understand and click through.

Frequently asked

What is an MCP server?

An MCP server is a process that speaks the Model Context Protocol — an open standard from Anthropic that lets AI tools like Claude Code, Cursor, and Codex call external tools and read external data. Swarm's MCP server exposes UX testing tools so your AI coding assistant can run real usability checks against your app without leaving the editor.

How do I install Swarm's MCP server?

Run `npx @useswarm/mcp@latest setup`. The one command registers Swarm with Claude Code and Codex CLI and signs you in. After it finishes, restart your editor and ask it to test your app.

Which editors does Swarm support?

Claude Code, Cursor, Codex CLI, and any editor that supports the Model Context Protocol. The setup command auto-configures Claude Code and Codex; manual config snippets are provided for everything else.

Does the MCP server need access to my code?

No. The MCP server only needs the URL of your running dev server (typically localhost:3000). It tunnels your localhost via Cloudflare so Swarm's cloud-hosted AI agents can navigate the app. Your source code never leaves your machine.

What tools does the Swarm MCP expose?

The main tools are `dev_test` (start a test run with a goal, audience, and target URL), `dev_watch` (stream structured UX issues as the agents find them), `dev_status` (check progress), and `dev_close` (end a session). Your editor's AI calls them as part of normal tool use.

Is it free?

The Free tier includes 5 lifetime test runs — enough to evaluate the MCP integration end-to-end. Paid plans start at $50/month for 70 runs/month with larger persona swarms.

Ship code, then test it from the same chat

Free tier includes 5 lifetime test runs. Enough to wire it up, run a real test against your app, and decide.

Get a free API keyRead the blog