BugTape docs

BugTape MCP tools

Every tool, its inputs and scopes.

Public tool list for agents connecting over the hosted MCP door. Delivery paths (listen vs webhook vs poll) live in 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)

Authorization: Bearer bt_pat_…

Ingest keys (bt_live_… / bt_test_…) are rejected — they are for SDK ingest only. MCP works on every plan (features.mcp). On Free and Prepaid credits, each agent read of a bug's captured events costs 2 credits (Free includes 150 a month); on Pro and above, reads are free.

Example client shape (field names vary by host):

{
  "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

HTTP at https://app.bugtape.ai/mcp is the supported path. Sign in with OAuth, or send an agent token. There is no published stdio package.

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

Agent PATs may call the agent verbs (create_bug, ack_bug, resolve_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. The one status change an agent PAT may make is resolve_bug: status → resolved, in its own org and granted projects, nothing else. 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

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.

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 for exact signing bytes, evidence upload, enrollment, and retries.

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

Users & live feed

Projects & org

Comments & watchers

MCP subscriptions (agent listen)

Both paths are supported. resources/subscribe acks interest and returns delivery hints under _meta["bugtape/delivery"]; event delivery still uses listen or GET /mcp?resource=….

1. resources/subscribe on bugtape://bugs/{bugId}/status, bare bugtape://bugs/{bugId}, or bugtape://projects/{projectId}/inbox
2. Receive _meta["io.modelcontextprotocol/subscriptionId"] plus _meta["bugtape/delivery"] with delivery:"listen", hint, listenTool:"listen", streamUrl:"/mcp?resource=<url-encoded uri>" (MCP EmptyResultSchema rejects unknown top-level keys, so these live under _meta only) and notifications/subscriptions/acknowledged
3. To receive updates, either call the listen tool, or open GET /mcp?resource=<uri> with Accept: text/event-stream (example: GET /mcp?resource=bugtape://projects/{projectId}/inbox). resources/subscribe alone does not open a stream; bare GET /mcp returns 405 with typed code SUBSCRIBE_STREAM_REQUIRES_RESOURCE and never streams.
4. Handle notifications/resources/updated, then resources/read — inbox pings are bug-level (new fingerprint), not occurrence-level
5. Or call listen directly. Optional afterCursor replays this project's retained events (Postgres on the hosted service, one sequence per project, 7 days and at most 1000 events). Pass 0 to replay the retained window. Omit afterCursor to wait only. Pass an inbox resourceUri to wait for or replay new-bug and agent_notify events. A dropped SSE stream is not a replay log.
6. 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.

listen kind: "cursor_expired"

listen puts JSON in a successful tool result. isError is not set, so the call did not fail and the agent must not retry the same cursor. A real event has a bugId. cursor_expired has no bugId. Do not treat that as "no events", an empty inbox, or a timeout.

{ "kind": "cursor_expired", "code": "cursor_expired", "cursorExpired": true, "message": "cursor expired, resync" }

kind is the field to branch on. It is cursor_expired when the cursor is from before this log, beyond a position this project issued, or older than the retained prefix (7 days and 1000 events per project). Cursors are positions within the selected project; the same number can exist in two projects. The server never returns another project's events.

Resync, in this order:

1. resources/read on bugtape://projects/{projectId}/inbox and take that open list as the current snapshot.
2. Call listen again on that same inbox URI with afterCursor: 0 (or omit afterCursor) and save the new cursor.
3. Do not pass the expired cursor again.

A status wait uses the same kind. After the inbox read, listen on bugId the same way and save that cursor.

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 (Allow: GET, POST) with JSON-RPC error.data = { code: "SUBSCRIBE_STREAM_REQUIRES_RESOURCE", hint, example } so agents learn to call listen or open GET /mcp?resource=…, while standard MCP clients treat 405 as optional SSE unavailable and continue with POST tools.

See agents.md for the full delivery contract and fix loop.

Tool effects for plugin hosts

Every tool advertises a title and explicit MCP read-only, destructive, idempotent and open-world hints. These describe effects; the existing workspace and scope gates still decide access. Pure retrieval is read-only. Captured-event reads (including repro context and file/screenshot occurrence checks) can use credits, so they are effectful. Recommended triage and listen can record handoff delivery. Changes, revocations, deletions and notification/model calls are classified separately. Hosts should refresh server metadata after a release.