> 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

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

{% hint style="info" %}
BugBug MCP access requires a **Pro or higher** BugBug plan. [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.

## What the agent can do

BugBug MCP tools can inspect tests, suites, runs, steps, groups, components, profiles, variables, project settings, documentation, and available run evidence. Authorized tools can also create or update test assets and start runs.

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

## 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 the authentication method supported by that environment and keep credentials in its 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)

### 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 access to 52 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 OAuth. These clients can use the hosted BugBug MCP endpoint through manual configuration.

</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. 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 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.