@bugbrain/mcp

BugBrain MCP Server

Connect your AI coding tools — Claude Code, Cursor, Codex, Windsurf, or your own agents — to the BugBrain QA platform over the Model Context Protocol. From your editor or CI you can run autonomous exploratory tests, curated test cases & plans, accessibility audits, and compliance scans, test a local site that isn't deployed yet, and gate a PR on a trust-scored result — without leaving your workflow.

Every other QA MCP runs the tests you wrote. BugBrain's finds the bugs you didn't — and proves the result is trustworthy, accessible, and compliant.

1. Quick start

a. Create an API key

In the BugBrain web app: Settings → API Keys → New key. Copy the sk_live_… value — it's shown once. An empty scope list = full access; scope it down for CI (see Scopes).

Keys are created by an Owner/Admin and act with admin-level capability. Treat them like passwords.

b. Add the server to your tool

Claude Code — claude mcp add:

claude mcp add bugbrain --env BUGBRAIN_API_KEY=sk_live_... -- npx -y @bugbrain/mcp

…or add it to your project's .mcp.json / client config directly:

{
  "mcpServers": {
    "bugbrain": {
      "command": "npx",
      "args": ["-y", "@bugbrain/mcp"],
      "env": {
        "BUGBRAIN_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Cursor — add the same block to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project).

Codex / Windsurf / other MCP clients — point them at the same command + env.

c. Use it

Ask your agent in plain English:

"Use bugbrain to list my projects, then start an exploratory run on the first one and tell me what's broken."

That's it. The agent discovers the bugbrain_* tools and drives them.

2. Configuration (environment variables)

Variable	Required	Default	Purpose
BUGBRAIN_API_KEY	yes	—	Your sk_live_… key.
BUGBRAIN_BASE_URL	no	https://api.bugbrain.tech	Point at a different BugBrain API (e.g. http://localhost:3001 for local dev, or your self-hosted instance).
BUGBRAIN_TUNNEL_CMD	no	cloudflared tunnel --url http://localhost:{port}	Command create_tunnel runs to expose your localhost. {port} is substituted.

3. Two ways to run it

Local stdio bridge (recommended for editors)

npx @bugbrain/mcp runs on your machine and proxies to the BugBrain cloud with your API key. This is the config shown above. It also unlocks create_tunnel (testing a local, un-deployed site), which the hosted server can't do.

Hosted Streamable HTTP (no install)

Point an MCP client at the hosted endpoint and pass your key as a bearer token:

URL:    https://mcp.bugbrain.tech/mcp
Header: Authorization: Bearer sk_live_...

Both transports expose the same tools (except create_tunnel, which is local-only).

4. What you can do (tool reference)

Long-running operations (runs, audits, scans, executions) are asynchronous: the start/run/execute tool returns immediately with an id and a pollWith hint; call the paired get_* tool to poll, or use watch_run for live progress. The MCP server auto-generates idempotency keys so a retrying agent never double-spends quota.

Projects & connection

Tool	What it does
bugbrain_connect	Validate the key; return org, plan, usage, and granted scopes. Call this first.
list_projects / get_project	List / fetch your projects.
list_environments / set_environment	View or switch a project's target environment.

Autonomous testing (the differentiator)

Tool	What it does
start_exploratory_run	AI explores the site and discovers bugs/issues nobody scripted. brief focuses it; targetUrl overrides the site (e.g. a tunnel URL).
start_regression_run	Like above, paired with get_run_comparison.
get_run_status / get_run_trace	Poll status / read the step-by-step agent trajectory.
list_run_issues / get_run_comparison	Issues found (severity, confidence, screenshots) / new-vs-resolved-vs-still-present diff.
watch_run	Stream live progress as MCP progress notifications until the run finishes.
cancel_run	Stop an in-flight run.

Web-Test — multi-agent QA swarm

Tool	What it does
run_web_qa	Point a swarm of QA agents at a URL or project — they explore, click flows, fill forms, probe edge cases, and file what they find as issues. Pass url or projectId; tune with breadth, speedTier, uploadTesting, devicePresetId. Returns a runId; poll get_web_qa_report.
run_duo_test	Two-actor test: two agents drive the app as different users at once to surface permission leaks (one user seeing another's data), broken collaboration, and state races. actorA uses the project credential; provide actorB's login inline (encrypted at rest) + a scenario.
get_web_qa_report	Consolidated, severity-categorized bug report for a Web-Test / duo run: status, swarm config, merged findings, issue count. Poll until COMPLETED.

Test cases & plans

Tool	What it does
create_test_case	Author a case from plain English.
generate_test_cases	AI-synthesize cases from the project's learned knowledge + recent runs.
list_test_cases / list_test_plans	Browse curated cases / plans.
execute_test_case / get_execution_result	Run one case → PASS / FAIL / INCONCLUSIVE + confidence.
get_execution_failure	Failing step + a local Playwright reproduce command + trace/HAR URLs.
execute_test_plan / get_test_plan_run	Run a whole plan (parallel) → pass/fail rollup.
test_changed_files	"Test what I changed": pass your diff's paths → it picks the most relevant cases and runs them.

Accessibility & compliance

Tool	What it does
run_accessibility_audit / get_accessibility_report	WCAG 2.1/2.2-AA audit → score, failing rules, per-page breakdown.
run_compliance_scan / get_compliance_report	SOC2 / GDPR / WCAG / PCI-DSS / HIPAA evidence mapping + risk level.
list_project_issues / triage_issue	List issues / get AI root-cause + suggested fix.
push_finding_to_tracker	File a finding into Jira / Linear.

Trust & CI (the moat)

Tool	What it does
get_run_observation	LLM-as-judge trust report: per-issue validity, failure root-cause, run-quality (1–5). Answers "can I trust this PASS?"
ci_gate	One call: run → wait → PASS/FAIL against failOn { severity, maxNewIssues, minTrust }. See CI.

Local-site testing

Tool	What it does
create_tunnel	Expose http://localhost:PORT via a secure tunnel so BugBrain can test it before you deploy. Returns a URL to pass as targetUrl. Local bridge only.

Governance (require the keys:admin / webhooks:write scopes)

Tool	What it does
mint_api_key / list_api_keys / revoke_api_key	Manage scoped API keys for CI / teammates.
register_webhook / list_webhooks / delete_webhook	Push-driven CI: subscribe a URL to run.completed / run.failed. See Webhooks.

Resources (attach as context)

Read-only project intelligence your agent can @-attach:

• bugbrain://projects/{projectId}/knowledge — the accumulated knowledge document.
• bugbrain://projects/{projectId}/coverage-gaps — untested states.
• bugbrain://projects/{projectId}/failure-patterns — flaky/unstable hotspots.

Prompts (slash-command workflows)

Pre-built multi-step workflows your client surfaces as commands:

• /bugbrain-pre-commit — test changed files + a11y, then gate.
• /bugbrain-pr-check — exploratory run + regression diff + trust score.
• /bugbrain-compliance-evidence — run a compliance scan and summarize evidence.
• /bugbrain-triage — list a run's issues and propose fixes.

5. Scopes

A key with no scopes = full access. To make a least-privilege key (e.g. for CI), pass a subset:

Scope	Grants
projects:read	List/read projects, environments
runs:read / runs:write	Read runs, observation / start + cancel runs
issues:read / issues:write	Read issues + triage / push to tracker
testcases:read / testcases:write / testcases:execute	Browse / author + generate / execute cases
testplans:read / testplans:execute	Browse / execute plans
accessibility:read / accessibility:run	Read report / run audit
compliance:read / compliance:run	Read report / run scan
environments:read / environments:write	View / switch environment
tunnels:create	Use create_tunnel
keys:admin	Mint/revoke API keys (hard-enforced server-side)
webhooks:write	Manage webhooks (hard-enforced server-side)

The server advertises only the tools your scopes allow, and the API re-checks on every call.

6. Testing a local site (before you deploy)

1. Run your app locally, e.g. on http://localhost:3000
2. Ask your agent: "create a tunnel for port 3000, then run an exploratory test on it."
   → create_tunnel returns a public URL (via cloudflared by default)
   → start_exploratory_run is called with targetUrl = that URL

Install the default tunnel binary once: cloudflared (no account needed for quick tunnels), or set BUGBRAIN_TUNNEL_CMD to your own tunnel command. create_tunnel only works on the local stdio bridge — the hosted server can't reach your machine.

7. Using it in CI

ci_gate is one blocking call that runs, waits, and returns a pass/fail verdict:

ci_gate {
  projectId: "proj_…",
  mode: "exploratory",            // or "accessibility" | "compliance"
  targetUrl: "https://pr-123.preview.app",   // optional
  failOn: { severity: "HIGH", maxNewIssues: 0, minTrust: 4 }
}
→ { gate: "PASS" | "FAIL", reasons: [...], runId, issueSummary, runQuality }

Use a scoped CI key (runs:write, runs:read, issues:read) and fail the pipeline when gate === "FAIL". The /bugbrain-pr-check prompt wires this up for you.

8. Webhooks (push instead of poll)

Subscribe a public https URL to run events so CI is notified instead of polling:

register_webhook { url: "https://ci.example.com/bugbrain", events: ["run.completed","run.failed"] }
→ { id, secret }      // store the secret — shown once

Every delivery is HMAC-signed: header X-BugBrain-Signature: t=<unix>, v1=<hex> where v1 = HMAC-SHA256(secret, "<t>.<rawBody>"). Verify it and enforce a timestamp tolerance to prevent replay. URLs are SSRF-checked; deliveries retry with exponential backoff.

9. Troubleshooting

Symptom	Cause / fix
Authentication failed … API key	BUGBRAIN_API_KEY missing/invalid/expired. Mint a new key.
A tool you expected isn't listed	Your key lacks that scope — mint a key with the needed scope (or a full-access key).
Concurrency limit reached (429)	Your plan's concurrent-run cap is hit; wait or upgrade. Don't loop.
quota exceeded (402)	Monthly run/token quota exhausted; upgrade or wait for reset.
create_tunnel errors	Install cloudflared or set BUGBRAIN_TUNNEL_CMD. Only works on the local bridge.
Run stays QUEUED forever	Self-hosted only: the worker isn't running.

10. Local development (running against your own API)

# Point the bridge at a locally-running BugBrain API:
BUGBRAIN_API_KEY=sk_live_... BUGBRAIN_BASE_URL=http://localhost:3001 npx @bugbrain/mcp

# Or debug interactively with the MCP Inspector:
BUGBRAIN_API_KEY=sk_live_... BUGBRAIN_BASE_URL=http://localhost:3001 \
  npx @modelcontextprotocol/inspector npx @bugbrain/mcp

Inside the monorepo, build then run from source: pnpm --filter @bugbrain/mcp build → node packages/mcp/dist/bin/stdio.js (a packages/mcp/smoke.mjs script is included for a quick end-to-end check).