# BugTape MCP tools

Public tool list for agents connecting over the hosted MCP door. Delivery paths (listen vs webhook vs poll) live in [agents.md](./agents.md).

## Remote door

- **URL:** `https://app.bugtape.ai/mcp`
- **RPC:** `POST` for `initialize` / tools / resources (JSON-RPC, stateless)
- **Listen:** `GET` may open an SSE stream with keep-alive (not a second RPC door)

```http
Authorization: Bearer bt_pat_…
```

Ingest keys (`bt_live_…` / `bt_test_…`) are rejected — they are for SDK ingest only. MCP requires a **Pro+** org (`features.mcp`).

Example client shape (field names vary by host):

```json
{
  "mcpServers": {
    "bugtape": {
      "url": "https://app.bugtape.ai/mcp",
      "headers": {
        "Authorization": "Bearer bt_pat_your_agent_token"
      }
    }
  }
}
```

Org-scoped agent PATs inherit organization on the API — `BUGTAPE_ORG_ID` / `X-BugTape-Org` are optional when the PAT is set.

## Authentication (do not invent a seventh model)

| Credential | How | Starts MCP? |
|------------|-----|-------------|
| Agent PAT `bt_pat_…` | `Authorization: Bearer …` on Streamable HTTP `/mcp`, or env `BUGTAPE_PAT` for stdio | **Yes** |
| Email + password | `BUGTAPE_EMAIL` + `BUGTAPE_PASSWORD` (JWT login; caches ~50 min) | **Yes** (human session) |
| Ingest key `bt_live_…` / `bt_test_…` | SDK / `POST /v1/ingest` only | **No** — rejected |

There is no PAT→JWT mint. Request Bearer PATs are request-scoped.

Agent PATs may call the agent verbs (`create_bug`, `ack_bug`, `listen` / `resources/subscribe`), the evidence tools (`get_repro_context`, `suggest_fix`, `get_bug`, `get_bug_events`, `get_occurrence_files`, `get_screenshot`, `get_bug_occurrences`, `get_bug_history`, `get_similar_bugs`) and the read-only routing tools (`list_recommended_critical`, `list_bugs`, `list_bug_groups`, `search_bugs`, `get_live_occurrences`, `get_bug_users`, `get_user_timeline`, `list_projects`, `get_project_stats`, `get_current_org`, `get_credit_usage`). Ordinary issue mutations — `update_bug`, `bulk_update_bugs`, `delete_bug`, `merge_bugs`, `add_comment`, `watch_bug` / `unwatch_bug` — stay **human-only**. Separately, PATs with the named work actions and a current project grant can claim work and submit/promote verification through the tools below. There is no `agent_resolved` tool.

## Tools

### Bug management

| Tool | Description |
|------|-------------|
| `get_repro_context` | **Agent-first** pack: bug metadata + compact console/network/error timeline (not raw rrweb). Prefer this for fix loops. |
| `list_recommended_critical` | Prefiltered agent inbox: new unique critical/high (or regressions). Prefer over `list_bugs` for “what to work on”. Rows also carry their project-scoped group totals — `group_key`, `instance_count`, `report_total`, `occurrence_count` (the `/groups` rule), `first_seen`, `last_seen`, `assignees` — plus the bug's own `assigned_to` and the group's org-scoped `assignee_name` sort key (additive, 2026-09-09, local), and the group's displayed evidence — `group_severity` (maximum member severity; the raw `severity` / `recommended_severity` stay the bug's own), `member_ids`, `signal_classes`, `signal_families`, `any_regression`, `platforms`, `browsers`, `oses`, `session_count`, `user_count` — never narrowed by a filter; `total` counts selected rows, not groups. |
| `ack_bug` | Agent acknowledge a bug (removes it from the recommended inbox). With `working`, optional `prUrl` (https) records the PR you opened. `working` and a new `prUrl` notify the project's humans through their existing destinations (`agent_update`). You open the PR; a human reviews it. |
| `list_bugs` | List bugs with filters (status, severity, project, search). Paginated. |
| `list_bug_groups` | Grouped triage view; accepts `platform`, `assignee`, `sort` (`last_seen`, `first_seen`, `count`, `severity`, `title`, `signal`, `assignee`) and `direction` (`asc`/`desc`). Each group is identified by `projectId` + `groupKey`. |
| `get_bug` | Get full bug details including reporters, AI summary, environment info. |
| `update_bug` | Update status, severity, or assignment. Add a triage note. **Human-only.** |
| `delete_bug` | Permanently delete a bug and all associated data. **Human-only.** |
| `search_bugs` | Full-text search across bug titles and descriptions. |
| `create_bug` | Create a new bug report using the MCP authenticated session. If `projectId` is omitted, the first project in the org is used. |
| `bulk_update_bugs` | Batch update up to 100 bugs at once by `ids`, project-scoped `groupRefs` (`{ projectId, groupKey }` from `list_bug_groups`/`search_bugs`) or legacy `groupKeys` (rejected with `GROUP_KEY_AMBIGUOUS` when a key spans projects). **Human-only.** |
| `merge_bugs` | **Destructive.** Merge N duplicate bugs into one canonical bug. **Human-only.** Max 19 sources per call. |
| `get_similar_bugs` | Find other bugs similar to a target bug, ranked by similarity score. |
| `get_bug_history` | Full audit trail of status/severity changes and assignments. |

### Claims and trusted verification

**Verified Close:** a fixer PAT records a proposal, then a different verifier PAT records an explicit `replay_assert` observation against the same `evidence_hash`. This credential separation prevents one PAT from self-verifying. It does not establish separate agent identity, require measured artifacts, or set `verified_fixed`.

Flow: fixer PAT `claim_issue` → bind pack/contract (`evidence_hash`) → `propose_fix` (never closes, never sets `verified_fixed`) → **different** PAT `verify_fix` with explicit `observation.reproduced`. Same fixer token on verify → `E_SELF_VERIFY`. Use `prepare_verification` / `submit_verification` / `promote_verification` for enrolled, signed, scope-wide measured proof. On MCP-related failure packs, `census_stamp` is a first-class optional field — record it when present. `watch_bug` stays human. Narrative: [agents.md — Verified Close](./agents.md#verified-close).

These tools require a current PAT and explicit project work grant. Actions and grants are rechecked on each call. Keep claim generation and fencingToken as strings. A capture key cannot call them. See the [public runner contract and offline signer](./runner-verification.md) for exact signing bytes, evidence upload, enrollment, and retries.

| Tool | Required PAT action | Result |
|---|---|---|
| `claim_issue` | `claim_issue` | Acquire a 60–900 second claim; retain its ID, generation and fencingToken. |
| `get_claim` | `claim_issue` | Read the current claim; expired ownership is not active. |
| `renew_claim` | `claim_issue` | Renew this PAT's live claim with the current fence. |
| `release_claim` | `claim_issue` | Release unfinished work without resolving or verifying the issue. |
| `complete_claim` | `claim_issue` | Record work completion with an applicable receipt; does not promote the issue. |
| `store_failure_pack` | `claim_issue` / `request_evidence` | Store content-addressed `agent_failure.pack` and birth/update the ReproContract `evidence_hash`. |
| `get_failure_pack` | work read scopes / `get_repro_context` | Read the linked pack when present (`get_repro_context` also embeds it). |
| `ensure_repro_contract` | `claim_issue` / `request_evidence` | Birth a ReproContract for the current generation from the first or pinned occurrence. |
| `get_repro_contract` | work read scopes / `get_repro_context` | Read contract status, `evidence_hash`, and `failure_predicate`. |
| `propose_fix` | `claim_issue` | Record PR/commit URL → `fix_proposed`. Never closes; never sets `verified_fixed`. |
| `verify_fix` | `submit_verification` | Separate-PAT assertion bound by `evidence_hash`; requires explicit `observation.reproduced`. Same PAT as fixer → `E_SELF_VERIFY`. MVP method `replay_assert` only (others 501). Does not flip `verified_fixed`. |
| `prepare_verification` | `submit_verification` | Issue a short-lived challenge for an enrolled runner; not a test pass. |
| `submit_verification` | `submit_verification` | Store exact scope, observations and artifact references. Unsigned assertions remain pending. |
| `get_verification_receipt` | `read_verification` | Read the historical receipt and current applicability. |
| `request_evidence` | `request_evidence` | Return authorized receipt artifact metadata; not hosted content or storage availability. |
| `promote_verification` | `submit_verification` | Requires a live claim and current trusted receipts covering every observed application/runtime and proposed repaired build. Success completes the claim atomically. |

`register_verification_runner`, `register_verification_device`, `list_verification_enrollment`, `revoke_verification_runner`, and `revoke_verification_device` require a **human organization admin** session. They do not let an agent create its own trust. Send only public runner keys. Device/runtime enrollment is explicit; simulator results cannot prove physical-device behavior.

Artifact reservation/upload is a separate HTTP capability. A PAT needs `create_bug` and a current project grant to write its CI log; `submit_verification` alone is insufficient. Check storage capabilities and ready/hash state. Application/build/installation registry management remains human manager/admin only.

### Events & analysis

| Tool | Description |
|------|-------------|
| `get_bug_events` | Session replay events (DOM, network, console, errors). Filter by type. |
| `get_bug_occurrences` | Occurrences for one bug. |
| `get_occurrence_files` | Paginated discovery of files/artifacts on an occurrence. |
| `get_screenshot` | Fetch a screenshot artifact by id (when present). |
| `suggest_fix` | AI-powered analysis: errors, failed requests, investigation steps. |
| `get_credit_usage` | Check AI credit wallet before expensive calls. |

### Users & live feed

| Tool | Description |
|------|-------------|
| `get_bug_users` | Who hit this bug (per end-user key) with counts and last occurrence. |
| `get_user_timeline` | Everything one end user hit, newest first, across bugs/projects. |
| `get_live_occurrences` | Recent occurrences across the org. |

### Projects & org

| Tool | Description |
|------|-------------|
| `list_projects` | List projects with bug counts. |
| `get_project_stats` | Aggregate stats: bugs by severity/status, report counts, recent activity. |
| `list_team` | Team members with roles and notification preferences. |
| `list_my_orgs` | Organizations the authenticated user belongs to. |
| `get_current_org` | Organization the MCP session is pinned to. |

### Comments & watchers

| Tool | Description |
|------|-------------|
| `add_comment` | Add a comment to a bug. Supports @email mentions. **Human-only.** |
| `get_bug_comments` | List comments on a bug. |
| `watch_bug` | **Human** notification preference (email/in-app). Not for agent waits. |
| `unwatch_bug` | Stop human watching. |
| `listen` | **Agent** wait on a real status transition or project inbox. Optional `toStatus` / durable `afterCursor` / `resourceUri`. The inbox wait also wakes with `kind: "agent_notify"` when a human pressed **Send to agent** or auto-notify fired. |

## MCP subscriptions (agent listen)

1. `resources/subscribe` on `bugtape://bugs/{bugId}/status`, bare `bugtape://bugs/{bugId}`, or `bugtape://projects/{projectId}/inbox`
2. Receive `_meta["io.modelcontextprotocol/subscriptionId"]` and `notifications/subscriptions/acknowledged`
3. Handle `notifications/resources/updated`, then `resources/read` — inbox pings are bug-level (new fingerprint), not occurrence-level
4. Or call `listen` (optional `afterCursor` for durable Tuesday-queue catch-up; pass an inbox `resourceUri` to wait/replay new-bug and `agent_notify` events)
5. `agent_notify` means a human or the project's auto-notify handed you this bug. Read `get_repro_context`, `ack_bug working`, and `ack_bug working` with `prUrl` once you open the PR. The MCP server reads handoffs from `GET /v1/projects/{projectId}/agent-notifications` (subscribe scope); collecting one marks it delivered on the issue page.

`GET /mcp` for SSE requires `Accept: text/event-stream`, an explicit subscribe-scoped Bearer PAT, and 1–32 `resource` query values from the same workspace. No resource filter returns 405 so standard MCP clients can continue with POST tools.

See [agents.md](./agents.md) for the full delivery contract and fix loop.