Connect your AI agent

Bugspray exposes Streamable HTTP MCP at /mcp on the app origin. Tool availability depends on deployment capabilities. Start the local app before connecting a local client.

Local stdio bridge
Hosted interactive client
Unattended hosted agent

For clients that accept mcpServers configuration, adapt this shape to their settings:

{
  "mcpServers": {
    "bugspray": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/to/bugspray", "run", "mcp"],
      "env": { "BUGSPRAY_URL": "http://127.0.0.1:3737" }
    }
  }
}

Use an absolute checkout path. No token is needed for ordinary loopback mode. The local stdio bridge also supports visible-browser authentication on the workstation.

An operator must issue a dedicated, expiring and revocable tenant-bound service token with only the mcp scope. Configure your client’s supported bearer-token mechanism against that tenant’s /mcp, injecting the token from secret storage. OAuth sign-in requires a human; a scheduled agent cannot complete it. Never use a Cloudflare account token or shared bootstrap REST token as this MCP credential.

Give the agent a concrete task

Read Bugspray's reporting guide and discover the available tools.
Find the Example Desk workflow for saving and reopening a view.
Read its exact saved expectations before testing.
Use only the dedicated synthetic test workspace.
Search existing findings before submitting a new one.
Verify the final state and inspect evidence; report only observed problems.
Record any untested expectations or unavailable capabilities explicitly.

The resources bugspray://reporting-guide and bugspray://ingestion-schema, tool get_reporting_guide and prompt report_verified_bug explain the live reporting requirements. MCP schemas, rather than this example prompt, define required arguments.

Use authenticated test profiles

Create a dedicated profile in Settings with login and protected verification URLs. Local Authenticate opens a visible browser. Complete sign-in, close the browser and let the server validate the saved state. For hosted visible sign-in, use authenticate_profile through the trusted local bridge. Hosted automatic reauthentication can use encrypted dedicated credentials when configured by an operator. Choose a ready profile returned by list_auth_profiles for protected findings. Scripts must not contain passwords or login flows. Hosted authenticated discovery and browser_* tools are profile/origin scoped; sessions expire after 15 idle minutes or two hours total and never return cookies or credentials. Per-PR preview discovery additionally needs an administrator-configured preview-origin allowlist. The supported pattern is an HTTPS pr-<digits> hostname, such as https://pr-*.preview.example.com; it is not a general wildcard. Trust only a suffix your preview operator controls. A matching hostname alone does not attest which revision is deployed.

Plan without overstating execution

plan_pr_suites reads current candidate evidence and proposes registered suites. plan_and_save_pr_suites explicitly requests persistence, which the server revalidates. Sampling requires a connected MCP host that negotiates sampling capability; stateless hosted sessions can return sampling_host_unavailable. There is no separate model account provisioned by local startup. Plans remain observation proposals with no test-skipping or auto-merge authority. Missing sampling retains conservative fallback and diagnostics. Use PR validation to distinguish plans, independent approval, dispatch and receipts. The repository’s scheduled cloud QA and PR sweep prompts are deployment-specific operating references, not generic prerequisites for connecting your own agent.

Start here

Understand Bugspray

Use Bugspray

Connect your AI agent

Give the agent a concrete task

Use authenticated test profiles

Plan without overstating execution

​Give the agent a concrete task

​Use authenticated test profiles

​Plan without overstating execution

Give the agent a concrete task

Use authenticated test profiles

Plan without overstating execution