> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/ai-testing/mcp.md).

# BugBug MCP

Connect AI agents to BugBug with the official MCP server: endpoint, setup for Claude, ChatGPT, Codex, Cursor, Copilot and VS Code, OAuth and bearer tokens, project access, workflow prompts and securit

BugBug MCP is BugBug's official Model Context Protocol server. It gives AI agents live access to BugBug through a set of tools and predefined workflow prompts.

{% hint style="info" %}
**Quick facts**

* Endpoint: `https://mcp.bugbug.io/mcp`
* Transport: Streamable HTTP. Both the 2025 MCP revisions and the 2026-07-28 revision are supported. The server is stateless.
* Authentication: OAuth sign-in with your BugBug account, or a bearer token.
* Over 70 [tools](/ai-testing/mcp/mcp-tools.md) and 8 workflow prompts.
* Plan: **Pro or higher**. [BugBug Skills](/ai-testing/skills.md) are available on **all plans**.
  {% endhint %}

## Recommended setup: BugBug Plugin

Install [BugBug Plugin](/ai-testing/plugin.md) through the CLI. It is the best setup route for supported clients because it configures MCP and installs BugBug Skills together. Choose your AI client:

{% tabs %}
{% tab title="Claude Code" %}

```bash
npx @bugbug-io/cli plugin --agent=claude
```

Requires Node.js 24 or newer.
{% endtab %}

{% tab title="Claude Desktop" %}

1. Open **Settings** → **Connectors** and click **Add custom connector**.
2. Enter the name `BugBug` and the remote MCP server URL `https://mcp.bugbug.io/mcp`. Leave the advanced OAuth settings empty and click **Add**.
3. Click **Connect** next to BugBug and complete the BugBug OAuth sign-in in your browser.
4. In a new chat, open the tools menu and make sure **BugBug** is turned on.

On Claude Team and Enterprise plans, an organization owner adds the connector in **Organization settings** → **Connectors**. Members then connect it in their own **Settings** → **Connectors**.
{% endtab %}

{% tab title="ChatGPT" %}

1. In ChatGPT, select **Plugins** in the sidebar (or open [chatgpt.com/plugins](https://chatgpt.com/plugins)).
2. Select **+**, then **Add custom MCP server**.
3. Enter the name `BugBug` and a short description, for example `BugBug test automation`.
4. Under **Connection**, choose **Public endpoint** and enter `https://mcp.bugbug.io/mcp`.
5. Set authentication to **OAuth**, review the warning, select **I understand and want to continue**, and then select **Create as a plugin**.
6. Complete the BugBug OAuth sign-in in your browser.
7. In a new chat, type `@` and select **BugBug** to use it.

If **Add custom MCP server** is not available, ask your ChatGPT workspace admin to allow custom MCP servers.
{% endtab %}

{% tab title="Codex" %}

```bash
npx @bugbug-io/cli plugin --agent=codex
```

Requires Node.js 24 or newer.
{% endtab %}

{% tab title="Cursor" %}

```bash
npx @bugbug-io/cli plugin --agent=cursor
```

Requires Node.js 24 or newer.
{% endtab %}

{% tab title="GitHub Copilot" %}

```bash
npx @bugbug-io/cli plugin --agent=copilot
```

Requires Node.js 24 or newer.
{% endtab %}

{% tab title="VS Code" %}

```bash
npx @bugbug-io/cli plugin --agent=vscode
```

Requires Node.js 24 or newer.
{% endtab %}

{% tab title="Manual configuration" %}
For a Streamable HTTP MCP client not supported by the installer, add this server entry to its MCP configuration. Keep any existing server entries and follow that client's documentation for the configuration-file location.

```json
{
  "mcpServers": {
    "bugbug": {
      "type": "http",
      "url": "https://mcp.bugbug.io/mcp"
    }
  }
}
```

{% endtab %}
{% endtabs %}

Restart the selected client if needed, then complete its MCP OAuth sign-in flow. The CLI plugin command does not accept a `--token` option. Use `--dry-run` to preview what it changes.

## Bearer token authentication for self-hosted clients

Clients that support Streamable HTTP and custom request headers can connect without an interactive OAuth flow. In OpenWebUI or another self-hosted client connected to Ollama, add an MCP server using the URL `https://mcp.bugbug.io/mcp` and set its `Authorization` header to `Bearer <BUGBUG_API_TOKEN>`. Use the project API token from **Integrations → API Token**. Ollama provides the model; the application hosting it must provide the MCP connection and header support. Client configuration fields vary by version.

For clients that accept an MCP server entry with a `headers` object, the configuration looks like this (replace the placeholder through your client's secret storage):

```json
{
  "mcpServers": {
    "bugbug": {
      "type": "http",
      "url": "https://mcp.bugbug.io/mcp",
      "headers": {
        "Authorization": "Bearer <BUGBUG_API_TOKEN>"
      }
    }
  }
}
```

An invalid or missing token is rejected with HTTP `401`.

The hosted endpoint uses HTTPS. A self-hosted MCP server can listen over plain HTTP, including on a VPN, but HTTP does not encrypt the bearer token or request data. Use TLS for connections beyond a trusted local boundary; a VPN does not add TLS to the MCP connection. Your client and any proxy must support Streamable HTTP and forward the authorization header.

## Projects and access

What the agent can reach depends on how it signed in:

| Sign-in               | Access                                                                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OAuth**             | Every project your BugBug account can access. The agent lists them with `bugbug_list_projects` and asks you to choose when it isn't clear which one you mean. |
| **Project API token** | Only the project the token belongs to.                                                                                                                        |

List and create tools take an explicit `projectId`. Other tools take the ID of the item they work on, such as a test, step or run.

## What the agent can do

BugBug MCP tools can inspect tests, suites, runs, steps, groups, components, folders, tags, profiles, variables, project settings, documentation, and available run evidence such as screenshots, DOM snapshots, console and network logs, and test inbox emails. Authorized tools can also create or update test assets and start runs.

For multi-step work the agent can use **code mode**: it writes a short JavaScript script that calls the BugBug API in a sandbox, and only the result goes back to the model. This saves calls and tokens. Deletes, stopping runs, removing or detaching components, converting components to groups and accepting visual regression baselines are never available in scripts. Use the dedicated tools for removing or detaching components.

See the [BugBug MCP tools reference](/ai-testing/mcp/mcp-tools.md) for the tool list, code mode limits and safe prompt examples.

## Workflow prompts

The server also provides prompts that guide the agent through common tasks. Your client shows them as prompts or slash commands, depending on the client.

| Prompt                     | Purpose                                                      |
| -------------------------- | ------------------------------------------------------------ |
| `plan-tests`               | Plan test coverage without changing anything in BugBug.      |
| `create-test`              | Build a test from a natural-language description.            |
| `review-test`              | Review an existing test for maintainability and reliability. |
| `refactor-test`            | Refactor tests, with explicit confirmation before changes.   |
| `debug-test-run`           | Diagnose a test run's failures with read-only tools.         |
| `heal-step-selector`       | Repair a failing step's selector.                            |
| `review-visual-regression` | Triage a failed visual regression comparison.                |
| `report-project-status`    | Produce a status report of the project for stakeholders.     |

## Alternative setup: BugBug MCP only

Use this only when you do not want the bundled skills or your client cannot use the plugin installer. Use the **Manual configuration** tab above to add the hosted endpoint to your client.

When supported, let the client complete the OAuth flow. For CI/CD or other non-interactive environments, use a bearer token and keep it in that environment's secret manager.

## Security best practices

* Verify the endpoint before connecting: `https://mcp.bugbug.io/mcp`.
* Prefer OAuth for interactive local use.
* Explicitly authorize creation, updates, deletion, imports, and test runs.
* Use read-only inspection first for planning, review, and debugging.
* Do not commit credentials to repositories.

### Related docs

* [BugBug Plugin](/ai-testing/plugin.md)
* [BugBug MCP tools](/ai-testing/mcp/mcp-tools.md)
* [BugBug Skills](/ai-testing/skills.md)
* [Public API](/integrations/public-api.md)

### FAQ

<details>

<summary>What is the BugBug MCP server, and what can AI agents do with it?</summary>

BugBug MCP is BugBug’s official Model Context Protocol server. It gives authorized AI agents tools for inspecting, creating and maintaining tests, suites, steps, components, tags, profiles and variables. Agents can also start test runs, monitor their progress and investigate failures using available run evidence.

</details>

<details>

<summary>How is BugBug MCP different from a browser-control MCP server such as Playwright MCP?</summary>

A browser-control MCP helps an agent explore and interact with a live website. BugBug MCP connects the agent to persistent regression assets, reusable components, run history and failure evidence managed in BugBug. They can work together: browser access provides application context, while BugBug MCP manages the shared regression suite.

</details>

<details>

<summary>Which AI clients can connect to BugBug MCP?</summary>

BugBug MCP works with Cursor, Claude Code, VS Code, Codex and GitHub Copilot through the BugBug Plugin. Claude Desktop and ChatGPT connect to the hosted endpoint as a custom connector or custom MCP server. Other AI clients can connect if they support Streamable HTTP MCP and either OAuth or a bearer authorization header. These clients can use the hosted BugBug MCP endpoint through manual configuration.

</details>

<details>

<summary>Which MCP protocol version and transport does BugBug MCP use?</summary>

Streamable HTTP at `https://mcp.bugbug.io/mcp`. The server supports clients on the 2025 MCP revisions and on the 2026-07-28 revision. It's stateless: there are no sessions, and responses are plain JSON, or a stream when a tool sends progress updates (for example while waiting for a run).

</details>

<details>

<summary>How does BugBug MCP authenticate and protect project data?</summary>

Interactive clients authenticate with BugBug through OAuth. Agents can only access projects available to the authenticated account, or only the token's project when you use a project API token. For safer operation, begin with read-only inspection and require human confirmation for actions that create, update, delete, import or run BugBug assets. Credentials should never be committed to a repository.

</details>

<details>

<summary>Which token do I use for a bearer connection?</summary>

The project API token from **Integrations → API Token**. It gives access to that one project. The same connection works for every tool, including `bugbug_upload_project_artifact`.

</details>

<details>

<summary>Which BugBug plans include MCP access?</summary>

BugBug MCP is available on the Pro plan and higher. BugBug Skills are available on all plans, but Skills alone do not give an AI agent live access to your BugBug projects.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bugbug.io/ai-testing/mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.