> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugspray.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your AI agent

> Use live MCP discovery and evidence-first reporting.

Bugspray exposes Streamable HTTP MCP at `/mcp` on the app origin. Tool availability depends on deployment capabilities. Start the [local app](https://docs.bugspray.io/quickstart.md) before connecting a local client.

> [tab] Local stdio bridge
>
> For clients that accept `mcpServers` configuration, adapt this shape to their settings:
>
> ```json theme={null}
> {
>   "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.

> [tab] Hosted interactive client
>
> Open **Settings** on your deployment and copy its generated OAuth setup. If the deployment uses a universal broker endpoint, select your registered workspace and approve the requested permissions. Access and tenant membership are both required. Reconnect the client after tool changes.

> [tab] Unattended hosted agent
>
> 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

```text theme={null}
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](https://docs.bugspray.io/guides/pr-validation.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.