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. |

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).