MCP Site QA for Cursor and Claude Code

You can attach Boidwatch to Claude Code with claude mcp add boidwatch -- boidwatch mcp (CLI installed and BOIDWATCH_API_KEY set). The MCP tools let the agent kick off persona-driven Chromium sessions against a URL and pull results—boidwatch_quick_check typically returns within about 45 seconds, or a run_id you resume with boidwatch_get_results (do not call quick_check again). Unlike browser-driving MCPs that click through a single agent session, Boidwatch’s job is a flock-based UX audit and a client-ready report. Cursor and other MCP clients can run the same local boidwatch mcp server once the CLI is installed.

Browser MCP vs UX-audit MCP

The SERP for “MCP website testing” is crowded with browser-driving tools: Playwright MCP, Cursor’s Browser tool, BrowserStack MCP, Monito, Assrt, and similar. Those servers let the coding agent operate a browser—navigate, click, assert DOM, debug a flow the agent is building right now.

That is useful. It is not the same job as shipping-proof UX QA.

| | Browser-driving MCP | Boidwatch MCP |

|---|---|---|

| Who drives the session | The coding agent, one browser at a time | A flock of Census-derived personas, each in real Chromium |

| Primary output | Interaction / debug feedback in the IDE | Ranked UX gaps + recommendations + report link |

| Best for | “Does this control work?” | “Would visitors complete the design intent?” |

| Complementary? | Yes — keep it for agent interaction | Yes — call it when you need an audit packet |

Boidwatch does not replace Playwright MCP or Cursor Browser. Keep those for interaction and debug. Add Boidwatch when the agent (or you) needs a persona-report / shipping-proof pass: real sessions, design-intent gap analysis, and a shareable finding set—not another way to click through the page yourself.

Install and authenticate once

Needs CLI v1.1.0 or later (llms.txt):

curl -fsSL https://boidwatch.com/install.sh | sh
# or
brew install boidwatch/tap/boidwatch

boidwatch version --json

Create an API key at app.boidwatch.com/settings/api-keys and export it:

export BOIDWATCH_API_KEY=fg_live_...

New accounts get 30 free credits (1 credit = 1 persona). No card required for that pool. Releases and README: github.com/boidwatch/cli.

Add the server (Claude Code + Cursor)

Claude Code

Exact command from llms.txt:

claude mcp add boidwatch -- boidwatch mcp

The CLI binary must be on PATH, and BOIDWATCH_API_KEY must be set in the environment the MCP process inherits. Restart the MCP host after changing the key.

Cursor (and other stdio MCP clients)

Point the client at the same local server: command boidwatch, args ["mcp"], with BOIDWATCH_API_KEY in the server env. In Cursor’s MCP config that is the usual mcpServers entry shape—no special Boidwatch flags beyond what the CLI already documents. Do not invent marketplace listing claims; wire the local binary the same way you would any other stdio MCP server.

Once connected, the agent sees tools including boidwatch_quick_check and boidwatch_get_results (plus boidwatch_teardown for a full flock and boidwatch_compare_runs to diff two completed runs).

The agent loop that works

Default edit-then-check loop:

1. boidwatch_quick_check with url (required) and optional design_intent (what the page should make visitors do). Five personas, ~5 credits. The tool call returns within about 45 seconds.

2. If the payload is still in progress (run_id, state, phase, next), call boidwatch_get_results with that run_id. Do not call quick_check again for the same run—the first call already created and billed it.

3. Read ranked gaps and recommendations from the compact results view. Fix blockers on the preview.

4. Re-check only after a new deploy (new URL or material change)—that is a new run.

Prompt the agent with something concrete:

> Run Boidwatch quick_check on this preview URL with design intent “Understand pricing and start a trial”; summarize the top gap and link the report.

For a thorough final pass before a client packet, use boidwatch_teardown (default 20 personas) or the CLI without --quick, then share from the report. Keep quick_check for the iterative loop.

When to escalate to peek or a full run

Three agent-callable depths, same account:

| Depth | How | Personas | Use when |

|---|---|---|---|

| Iterative QA | MCP boidwatch_quick_check or CLI --quick | 5 | Edit → check → fix inside Cursor / Claude Code |

| Shipping gate | Authenticated POST /v1/peek | 3 (capped) | One strongest finding before the client URL goes out |

| Client packet | MCP boidwatch_teardown or CLI full run | 20 (default) | Full ranked gaps + shareable report |

The 5- and 20-persona counts and ungated complete reports require wallet top-up / a paid run outside the free cap. Without wallet top-up, ordinary runs remain capped at 3 personas with gated results, even with signup credits. Peek remains the force-free capped gate, including on paid accounts: 3 personas, 15 steps, a 5-minute hard stop, and one strongest finding.

Caveat: prefer the documented CLI --quick path and MCP tools until peek appears in public llms.txt. Authenticated POST /v1/peek on https://api.boidwatch.com is an adjacent agent path for a capped shipping gate (3 personas, 15 steps, 5-minute hard stop, one strongest finding). Treat it as complementary to MCP—not a substitute for the documented quick/full flock when you need the report packet. Details and agent SOP: Agent-native shipping proof.

Failure modes agents must handle

Align agent retries with CLI exit behavior (llms.txt; full table via boidwatch commands | jq .exit_codes):

| Exit | Meaning | Agent action |

|---|---|---|

| 0 | Success | Read gaps; fix or accept |

| 2 REACHABILITY_ERROR | URL unreachable or bot-protection challenge; run not created; no credits charged | Fix URL / access; then retry create |

| 7 | Wait timed out; run continues | Poll / boidwatch_get_results with run_id; do not recreate |

| 9 | Check failed (--assert-* or always-on entry-block: no persona past entry URL) | Treat as a check result (stdout carries results/assertions); fix the page or entry path |

With JSON output, follow next when present—never create the same run again. retryable says whether repeating the same call can help. Failed runs are refunded automatically; cancelled runs are not.

FAQ

How do I run website QA from Cursor or Claude Code using MCP?

Install the Boidwatch CLI (≥ v1.1.0), set BOIDWATCH_API_KEY, add the server with claude mcp add boidwatch -- boidwatch mcp (or point Cursor’s MCP config at boidwatch mcp), then ask the agent to call boidwatch_quick_check on the preview URL with a one-line design intent.

What’s the difference between Playwright MCP and a UX-audit MCP?

Playwright MCP (and Cursor Browser, BrowserStack MCP, etc.) drive a browser for the coding agent to interact and debug. A UX-audit MCP like Boidwatch dispatches a persona flock in real Chromium and returns ranked gaps plus a client-ready report. Complementary, not interchangeable.

How do I add Boidwatch as an MCP server?

claude mcp add boidwatch -- boidwatch mcp after CLI install and API key export. Other MCP clients use the same local command/args over stdio.

What does boidwatch_quick_check return, and how do I resume a run?

Within about 45s: either compact ranked results, or {run_id, state, phase, next} if still running. Resume with boidwatch_get_results and that run_id. Do not call quick_check again for that run.

Ask the agent to run it

Install the CLI, add the MCP server, and ask:

> Run Boidwatch quick_check on this preview URL with design intent X; summarize the top gap and link the report.

Docs for agents: boidwatch.com/llms.txt · keys: API keys settings · CLI: github.com/boidwatch/cli.