# Install BugTape MCP

BugTape MCP is a remote HTTP server. It works on every plan, Free included. On Free and Prepaid credits, each agent read of a bug's captured events costs 2 credits (Free includes 150 a month); other reads are free. On Pro, reads are free. Capture keys (`bt_live_` / `bt_test_`) are rejected.

Endpoint: `https://app.bugtape.ai/mcp`

## Try it first: the public demo (no signup)

`https://app.bugtape.ai/demo/mcp` is a public, read-only BugTape MCP server. It needs no account and no key. It holds one sample workspace, **BugTape Demo**, with one project, **John's Shoes**: a sample shop whose captures include a checkout `500` with its server-side `TypeError`, a Safari JavaScript error, a hung payment request, a rage click and a `404`. The people and hosts in it are fictional.

```bash
claude mcp add --transport http bugtape-demo https://app.bugtape.ai/demo/mcp
```

Other clients take the same URL with no auth header (Cursor: `{"url": "https://app.bugtape.ai/demo/mcp"}` under `mcpServers.bugtape-demo`). Then ask: *"Find the most urgent issue in John's Shoes, read its repro context, and tell me the root cause and the fix."*

The demo lists read tools only (`list_recommended_critical`, `list_bug_groups`, `get_bug`, `get_repro_context`, `get_bug_events`, `get_bug_occurrences`, `get_bug_users` and similar). Acknowledging, claiming, commenting and the listen stream need your own workspace. Copy-paste configs for every client: [bugtape-examples](https://github.com/jackfieldman/bugtape-examples).

## Fastest: one command

```bash
npx -y bugtape connect claude   # or: cursor, codex, grok, grok-bot
```

It prints a link and a code. Open the link (or send it to whoever owns the workspace), check the code, click **Allow**, and the agent is added. This works on servers and in cloud agents with no browser. Then the same command with `init` sets up capture in your repo: project, key, install steps with the release, and one test report. See [the CLI](/docs/cli/).

## Sign in without a token (OAuth)

Every client that supports MCP sign-in needs only the URL. It opens a BugTape page where you pick the workspace and what the agent may do, then click **Allow**. The connection appears on the Team page, where you can remove it.

| Client | Add BugTape |
|---|---|
| Claude Code | `claude mcp add --transport http bugtape https://app.bugtape.ai/mcp`, then `/mcp` and choose BugTape |
| Claude (web, desktop, mobile) | Settings → Connectors → Add custom connector → `https://app.bugtape.ai/mcp` |
| ChatGPT | Add a custom connector (developer mode) with `https://app.bugtape.ai/mcp`; ChatGPT opens the sign-in page |
| Cursor | Add `{"url": "https://app.bugtape.ai/mcp"}` under `mcpServers.bugtape`; Cursor shows **Needs login** |
| Grok (web) | Connectors → New Connector → Custom → `https://app.bugtape.ai/mcp`; complete authentication. Team admins provision Business/Enterprise connectors first. See [plugins](./plugins.md) for support and qualification limits |

BugTape publishes `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-authorization-server`, answers `401` with `WWW-Authenticate: Bearer resource_metadata=…`, accepts Client ID Metadata Documents, dynamic client registration and PKCE (S256), and rotates refresh tokens.

## With a token

Prefer the host’s native OAuth sign-in where supported. For a client that needs a token, make a token on the Team page (**Add an agent**) or with `npx -y bugtape login`, then paste it as below. Grok bots on the xAI API can use this way; Grok Build also supports native OAuth for remote HTTP MCP.

Updated: 2026-10-02.

### Claude Code

```bash
claude mcp add --transport http bugtape https://app.bugtape.ai/mcp \
  --header "Authorization: Bearer bt_pat_YOUR_TOKEN"
```

### Cursor

Save in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (user):

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

### Codex

Set `BUGTAPE_MCP_TOKEN` in the environment that launches Codex. Load it from your password manager or OS keychain. Do not put the PAT in shell history, `config.toml`, source files, or the repository.

```bash
codex mcp add bugtape \
  --url https://app.bugtape.ai/mcp \
  --bearer-token-env-var BUGTAPE_MCP_TOKEN
```

Codex stores the URL and environment variable name in its TOML configuration, then reads the token from `BUGTAPE_MCP_TOKEN` when it connects. Cursor uses the `mcpServers` JSON above; do not use that JSON for Codex.

### Grok / HTTP MCP

Point the client at `https://app.bugtape.ai/mcp` with header `Authorization: Bearer bt_pat_YOUR_TOKEN`. Same JSON shape as Cursor.

## The agent loop

What the agent may do comes from its **permissions** (scopes). **Pick up and fix** gives `subscribe`, `get_repro_context` and `suggest_fix`; **Follow and read** drops `suggest_fix`; sign-in adds `create_bug` (file new issues) unless you untick it, and `setup_capture` (create projects and capture keys) when you tick it. Permissions are not tool names; there is no `subscribe` tool.

**The agent loop** (tool names as your agent sees them):

1. `subscribe_feed` with `deliveryFeed: "urgent_critical"` and `notify: true`. This elects the feed the agent is woken for. `urgent_critical` is recommended for agent tokens; `all` and `ui_ux` also exist.
2. `listen` with `resourceUri: "bugtape://projects/{projectId}/inbox"`. It waits until a bug in that feed arrives, or until BugTape hands the agent a bug (auto-notify or **Send to agent**, event `agent_notify`).
3. `get_repro_context` for that bug: what the user did, the failed request, the console and the stack.
4. `ack_bug` with `action: "working"`, then again with `prUrl` when the pull request is open. Your team is told in Slack or by webhook.

No listener running? Start with `list_recommended_critical`, then `get_repro_context`. Do not dump `list_bugs`.

## After connect

A client that will not connect: work through the [MCP server not working checklist](https://bugtape.ai/guides/mcp-server-not-working/) (Claude Code, Cursor and Codex).

First useful request: “Call `subscribe_feed` with `urgent_critical`, then `list_recommended_critical`, select the highest-ranked issue and call `get_repro_context` for it. Report the captured evidence and any gaps, then `listen` on the project inbox for the next one.” Do not start with a dump of `list_bugs`.

Paste the [AGENTS.md snippet](./examples/AGENTS.md) into the repo so the agent uses the ranked inbox. Full contract: [Agent setup](./agents.md). Tool list: [MCP tools](./mcp-tools.md).

## Directory listings

Machine files for MCP directories: [`mcp.json`](./listings/mcp.json) and [`smithery.yaml`](./listings/smithery.yaml). Submitting them to Smithery, PulseMCP, mcp.so, Cursor directory, Claude connectors, and Glama is a manual step. The public URL and auth header above are the source of truth.

## Plugin package

[Install the BugTape plugin](./plugins.md) for bundled setup, triage, reporting and verification guides in Claude Code, Codex or Grok Build. The same page covers chat app connections and current listing status.