---
title: "Connect the MCP server"
description: "Connect a coding agent or chat client to the Bugbearer MCP server at https://app.bugbearer.com/api/mcp. Sign in with OAuth in your browser. Setup for Claude Code, Codex, Cursor, VS Code, Gemini CLI, Claude and ChatGPT."
---

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

# Connect the MCP server

The Bugbearer MCP server lets an agent connect an app, send a setup brief, run setup, send environment values, manage the boot plan, start test runs, review Draft test cases, and read bugs and runs. You approve the agent in your browser first. No API key is involved.

> **Caution**
>
> The MCP server is not live in production yet. The server URL works once Bugbearer's MCP release is live. Until then, this page describes the upcoming release.

> **Note**
>
> Two MCP servers belong to Bugbearer. **This page** covers the product server, `https://app.bugbearer.com/api/mcp`. It acts on your workspace and needs sign-in. The docs site has its own server at `https://docs.bugbearer.com/mcp`. It only searches these docs and needs no sign-in. The **Copy MCP URL** button on this site copies the docs server URL.

## Server URL

```text
https://app.bugbearer.com/api/mcp
```

This is the host you sign in to. If you run Bugbearer yourself, the URL is `<your app URL>/api/mcp`.

The endpoint answers `POST` only. `GET` and `DELETE` answer 405. The server has no sessions. It accepts MCP protocol version 2026-07-28 and the older versions 2025-06-18 and 2025-11-25. The older versions run in the SDK's stateless legacy mode. See [Which clients work](#which-clients-work).

## What sign-in looks like

1. Your client opens your browser on the Bugbearer sign-in page.
2. You sign in with GitHub or Google.
3. The consent page shows the agent, the scopes it asks for and the workspace it gets. You select **Allow**.
4. The browser hands control back to the client. The client now holds a token.

The client names itself with a Client ID Metadata Document (CIMD), a public URL that describes the client. You do not create an OAuth client and you do not paste a key. A client that cannot use CIMD, such as Cursor or Gemini CLI, registers itself by dynamic client registration (DCR). DCR is on by default. A server turns it off with `MCP_ALLOW_DCR=0`. The consent page marks a DCR client "Unverified" and shows where the browser returns, because the client chose its own name.

> **Note**
>
> Only a real sign-in can approve an agent. The development skip-sign-in cookie cannot.

## Scopes

| Scope | Lets the agent | Status |
| --- | --- | --- |
| `bugbearer:read` | Read apps, bugs, runs and Draft test cases | Available |
| `bugbearer:setup` | Connect apps, run and control setup, and read, propose and validate the boot plan | Available |
| `bugbearer:env` | List environment variable names and decisions, and send environment values with an upload command or a review link | Available |
| `bugbearer:run` | Start test runs, and approve or reject Draft test cases | Available |

Every token needs `bugbearer:read`. A tool that needs another scope makes the client ask you to approve again with that scope.

An approval covers every app in your workspace. You cannot pick single apps yet.

## Which clients work

Status as of 6 November 2026. Claude Code, Codex and Cursor were tested against a local development server.

| Client | Status | Known requirement |
| --- | --- | --- |
| Claude Code | **Tested** with 2.1.318 | Signs in with CIMD. Consent and tool calls work. |
| Codex | **Tested** with 0.165.0 | Signs in with CIMD (`https://chatgpt.com/oauth/codex/client.json`). The consent page shows "Connect Codex". `codex exec` called `whoami` and `list_bugs`. |
| Cursor | **Tested** with cursor-agent 2026.09.12 | No CIMD. Registers by DCR, which is on by default. Tested with DCR on: it signs in and lists the 9 tools the server had then. With DCR off, sign-in fails. |
| VS Code | Not tested yet | Supports CIMD. |
| Gemini CLI | Not tested yet | No CIMD. Registers by DCR, which is on by default. |
| Claude (claude.ai, desktop) | Not tested yet | Needs the public URL. It reaches the server from Anthropic's network, never your machine. |
| ChatGPT | Not tested yet | Needs the public URL. It supports CIMD. |

Cursor and Gemini CLI need DCR. If a server turns DCR off, use Claude Code or Codex. This table changes when another client is tested.

## Set up your client

### Claude Code

**Status: Tested** with Claude Code 2.1.318. CIMD sign-in, consent and tool calls work.

1. **Add the server**

   ```sh
   claude mcp add --transport http bugbearer https://app.bugbearer.com/api/mcp
   ```
2. **Sign in**

   In Claude Code, run `/mcp`, select **bugbearer**, then **Authenticate**. Or run this in your shell:

   ```sh
   claude mcp login bugbearer
   ```
3. **Approve**

   Your browser opens. Sign in, check the consent page, and select **Allow**.

To share the server with a project, put this in `.mcp.json`:

```json
{
  "mcpServers": {
    "bugbearer": {
      "type": "http",
      "url": "https://app.bugbearer.com/api/mcp"
    }
  }
}
```

A `claude -p` run cannot sign in. Sign in from an interactive session first.

### Codex

**Status: Tested** with Codex CLI 0.165.0. It registers by CIMD, the consent page shows "Connect Codex", and `codex exec` called `whoami` and `list_bugs`.

```sh
codex mcp add bugbearer --url https://app.bugbearer.com/api/mcp
codex mcp login bugbearer
```

Or add it to `~/.codex/config.toml`:

```toml
[mcp_servers.bugbearer]
url = "https://app.bugbearer.com/api/mcp"
```

Codex picks CIMD on its own when the server offers it. It needs no flag.

The ChatGPT desktop app and the Codex IDE extension share this config. In their settings, open **MCP servers**, then **Add server**, then **Streamable HTTP**.

### Cursor

**Status: Tested** with cursor-agent 2026.09.12. Cursor has no CIMD, so it registers by DCR. DCR is on by default. Tested with DCR on: it registers, signs in and lists the 9 tools the server had then. With `MCP_ALLOW_DCR=0`, `cursor-agent mcp login` fails with "Incompatible auth server: does not support dynamic client registration".

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "bugbearer": {
      "url": "https://app.bugbearer.com/api/mcp"
    }
  }
}
```

Then open Cursor's MCP settings and sign in to **bugbearer**.

### VS Code

**Status: Not tested yet.**

Run this in a terminal:

```sh
code --add-mcp '{"name":"bugbearer","type":"http","url":"https://app.bugbearer.com/api/mcp"}'
```

Or open this link. VS Code shows the server for you to review before it installs:

[Install in VS Code](vscode:mcp/install?%7B%22name%22%3A%22bugbearer%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapp.bugbearer.com%2Fapi%2Fmcp%22%7D)

Or add it to `.vscode/mcp.json`:

```json
{
  "servers": {
    "bugbearer": {
      "type": "http",
      "url": "https://app.bugbearer.com/api/mcp"
    }
  }
}
```

VS Code Insiders uses `vscode-insiders:` in place of `vscode:` in the link.

### Gemini CLI

**Status: Not tested yet.** Gemini CLI has no CIMD, so it registers by DCR, which is on by default.

```sh
gemini mcp add -t http bugbearer https://app.bugbearer.com/api/mcp
```

Or add it to `settings.json`:

```json
{
  "mcpServers": {
    "bugbearer": {
      "httpUrl": "https://app.bugbearer.com/api/mcp"
    }
  }
}
```

Gemini CLI starts the sign-in from its `/mcp auth` command.

### Claude

**Status: Not tested yet.** This covers claude.ai on the web, Claude desktop and Claude mobile. Claude reaches the server from Anthropic's network, so the server needs a public URL. The hosted URL is public. A server on your own machine is not.

1. Open **Customize**, then **Connectors**, then **Add custom connector**. On a Team or Enterprise plan, an Owner adds it under **Organization settings**, **Connectors**, **Add**, **Custom**. Members then select **Connect**.
2. Enter the URL `https://app.bugbearer.com/api/mcp`. Leave the OAuth client ID and secret empty.
3. Select **Add**. Then connect. Your browser opens the Bugbearer consent page.

This link opens the Add dialog with the fields filled in. It changes nothing until you confirm:

[Add Bugbearer to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Bugbearer\&connectorUrl=https%3A%2F%2Fapp.bugbearer.com%2Fapi%2Fmcp)

### ChatGPT

**Status: Not tested yet.** ChatGPT reaches the server over the public internet, so the server needs a public URL. ChatGPT calls custom MCP servers "plugins". Account and workspace policies can block custom servers.

1. Open [ChatGPT Plugins](https://chatgpt.com/plugins).
2. Select the plus button, then **Add custom MCP server**.
3. Enter a name and a description.
4. Under **Connection**, enter `https://app.bugbearer.com/api/mcp`.
5. Configure authentication, review the risk warning, and select **I understand and want to continue**.
6. Select **Create as a plugin**, then sign in.

ChatGPT has no install link for custom servers.

## Check the connection

Ask the agent to call `whoami`. It returns your user, your workspace and the scopes the agent holds. If `scopes` lacks `bugbearer:setup`, approve the agent again with that scope.

When the connection works, go on to [Agent-driven onboarding](https://docs.bugbearer.com/agent-onboarding).

## Tools

| Tool | Scope | Returns |
| --- | --- | --- |
| `whoami` | read | The user, the workspace, the granted scopes, and the granted apps (`null` means all apps). |
| `list_bugs` | read | Bugs with id, title, severity, status and app. Newest first, at most 50. Filter by `appId` or `status`. |
| `get_bug_bundle` | read | One bug: steps, evidence, expected and actual result, and still references. No image bytes. |
| `get_run` | read | A run's status, case counts by status, cost, and the bugs it found. |
| `list_runs` | read | Runs with id, app, status, trigger, times, cost, case counts and bug counts. Newest first, at most 50 per page. Filter by `appId`. |
| `list_draft_cases` | read | The Draft test cases of an app, then the rejected ones. Each case has title, feature, start route, instructions and expected outcomes. At most 50 per page. |
| `connect_app` | setup | Connects an app. See below. |
| `get_brief_schema` | setup | The JSON Schema of the setup brief and the rules for writing it. |
| `submit_brief` | setup | `{ ok: true }`, or `{ ok: false, errors }` with a path and reason for each error. |
| `start_setup` | setup | `{ sessionId }`. Starts the setup agent for a repo app. |
| `get_setup_status` | setup | Setup phase and status, target state, names of env variables waiting for a value, test accounts that need a password, whether a model key is missing, and open questions for you. |
| `answer_setup_question` | setup | `{ sessionId, status, seq }`. Sends a plain-text reply to the running setup agent. |
| `cancel_setup` | setup | `{ sessionId, status }`. Stops the setup session of the app. |
| `resume_setup` | setup | `{ sessionId, status }`. Restarts a cancelled, failed or interrupted setup session from its saved history. |
| `get_boot_plan` | setup | The saved boot plan (no values), when it last booted clean, the latest validation result, and the JSON Schema and rules for a plan. |
| `propose_boot_plan` | setup | `{ saved: true }`, or `{ saved: false, problems }`. Saves a boot plan when it has no problems. |
| `validate_boot_plan` | setup | The result of a real boot of the saved plan, per step, with scrubbed logs. |
| `list_env_status` | env | Each env variable name of an app, what Bugbearer decided, whether a value is stored, whether a value is missing, and whether the boot plan reads it. Never values. |
| `set_env` | env | An upload command with a one-use token, or a review link. See below. |
| `start_run` | run | `{ runId, status }`. Plans test cases from your brief and starts the run. |
| `approve_cases` | run | `{ changed }`. Approves Draft test cases by id. |
| `reject_cases` | run | `{ changed }`. Rejects Draft test cases by id, with a reason. |

**`connect_app`** takes `{ kind: "repo", repo: "owner/name", subdir? }` or `{ kind: "url", url, notProduction: true, name? }`. It returns `next`:

- `run_setup`: the repo app exists. Send a brief or call `start_setup`.
- `install_github_app`: Bugbearer cannot read the repo. The result has an `installUrl` for you to open. Nothing is created. Call `connect_app` again after you install.
- `ready`: the URL app is saved.

A URL app must be public. `connect_app` refuses local, private and cloud metadata addresses.

`connect_app` needs a grant for all apps. `start_setup` uses the brief you submitted, if there is one. It works for repo apps only.

**`answer_setup_question`** takes `appId` and `text`, at most 4000 characters. The text is a reply to a question from `get_setup_status`. The tool refuses any text that has a `KEY=value` assignment and points to `set_env`. It works only while the setup session runs or waits for input. For a session in any other state, call `resume_setup` or `start_setup` first. `cancel_setup` refuses a finished setup. `resume_setup` refuses a running or finished setup.

**`set_env`** takes only `appId` and an optional `mode`. No input of this tool carries a value. It works for repo apps only.

- `upload` (default): the result has a `command`, a `curl` command with a one-use token, and `expiresAt`. The token expires after 15 minutes. The agent runs the command in a shell. It replaces `.env.test` with the path of the env file. The agent must not read, print or open the file. A new `set_env` call for the same app revokes the earlier unused token.
- `link`: the result has a `url` of the setup review screen. You open it while you are signed in and type the values there.

The upload reply lists names and decisions, never values. A decision is `stored`, `ours`, `replaced`, `left_empty`, `ignored` or `refused`. Bugbearer refuses live keys. An upload has these limits: 256 KB, 200 names, and 5000 characters per value. If a setup agent is running, it receives the names and decisions. Otherwise a saved boot plan boots again. See [Secrets and test keys](https://docs.bugbearer.com/secrets-and-test-keys).

**`list_env_status`** gives each name a `decision` (`used`, `ours`, `replaced`, `left_empty` or `ignored`, or `null`), `stored`, `missing` and `inPlan`. `inPlan` is false when the boot plan does not read the stored value yet. Use it to check an upload.

**`propose_boot_plan`** and **`validate_boot_plan`** refuse while a setup runs for the app. A plan holds no values. It uses `{{secret:NAME}}` and `{{user:KEY}}` templates. `validate_boot_plan` boots the saved plan for real and waits up to 30 seconds. If the boot is not done, it returns `status: "running"`. The agent reads progress with `get_boot_plan` and calls `validate_boot_plan` again only after the boot ends. One validation runs per app at a time. `resetData: true` also deletes the data volumes of the app.

**`start_run`** takes `appId` and a `brief` of 3 to 4000 characters that says what to test. Bugbearer plans the test cases and starts the run. No person presses Start. Poll `get_run`. The app's case and cost limits apply. If a test account has no stored password, the tool refuses and names the account. You add the password in the web app.

**`approve_cases`** and **`reject_cases`** take `appId` and at most 50 case ids. `reject_cases` also needs a `reason`. The call is all or nothing. An id from another app, or a case that is not a Draft, refuses the whole call. An approved case runs on every scheduled run. The agent must ask you before it calls `approve_cases` or `reject_cases`.

## Limits

- `connect_app`, `submit_brief`, `start_setup`, `set_env`, `propose_boot_plan` and `validate_boot_plan` each allow 10 calls per user per hour, counted separately for each tool.
- `start_run` allows 10 runs per workspace in a rolling 24 hours, counted over runs started through agents. It allows one active agent run per app. A draft or planning run holds the slot of the app for 30 minutes after its last change.
- `approve_cases` and `reject_cases` take at most 50 case ids per call.
- `list_bugs`, `list_runs` and `list_draft_cases` return at most 50 items per page. Read `nextOffset` to continue. `get_bug_bundle` returns at most 20 items per evidence list.
- A refused call returns a short message with no internal detail.
- A request that declares a body larger than 256 KB is refused.

## Safety

- Results of `whoami`, `list_bugs`, `get_bug_bundle`, `get_run`, `get_setup_status`, `list_env_status`, `list_runs`, `get_boot_plan`, `validate_boot_plan` and `list_draft_cases` carry an `untrusted_note`. Their `data` field holds text from the app under test. Agents must treat it as data, not instructions.
- No tool returns a secret value, and no tool input carries one. The setup and env tools list variable names only, the brief has no field for a value, and `answer_setup_question` refuses text with a `KEY=value` assignment. Values travel only through the `set_env` upload command or the review screen.
- Every call checks the token's scopes and the grant again. If you disconnect an agent, it loses access on its next call.

## Disconnect an agent

In the app, open Settings, Workspace, **Connected agents**. Each row shows the agent, its scopes and when it was last used. Select **Disconnect**. You can approve the agent again later.

## Use a skill

This site publishes a skill, `connect-bugbearer-mcp`, that tells a coding agent how to connect and the order of calls. Agents that read `/.well-known/agent-skills/` can install it.

## For agents

The Bugbearer MCP server URL is `https://app.bugbearer.com/api/mcp`. This page is also available as Markdown at `/onboarding-mcp/index.md`. The documentation index is `/llms.txt`.

Source: https://docs.bugbearer.com/onboarding-mcp/index.mdx