---
title: Remote MCP Server
---

# Remote MCP Server

## Overview

The bitdrift remote [Model Context Protocol](https://modelcontextprotocol.io/){:target="_blank"} (MCP) server connects AI agents and chat apps to your bitdrift account, so they can triage issues, investigate sessions, read charts, and create workflows, dashboards, and alerts. There is nothing to install: add the URL to your client and sign in with your bitdrift account.

!!! info "Server URL"
    ```text
    https://mcp.bitdrift.ai/
    ```

Use either the MCP server or the [CLI + Agent Skills](skills.md), not both. Choose the CLI if your agent can't connect to remote MCP servers. See [Security and permissions](../ai.md#security-and-permissions) for what your agent can access.

## Quickstart

Choose a plugin or add the server URL directly, then sign in with your bitdrift account.

### Plugin (recommended) { #plugin }

Install only the `bitdrift-mcp` plugin from the [bitdrift plugin marketplace](https://github.com/bitdriftlabs/bd-skills){:target="_blank"}.

#### Apps and IDEs { #plugin-apps-and-ides }

=== ":fontawesome-brands-openai: ChatGPT"

    Plugins with MCP servers run in the ChatGPT desktop app:

    1. Open **Plugins** > **Personal**, then select **Add** > **Add a marketplace**.
    2. Enter `https://github.com/bitdriftlabs/bd-skills` and add the marketplace.
    3. Under **Personal**, open **bitdrift MCP** and select **+** to install it.
    4. Sign in with your bitdrift account when prompted, then start a new chat.

    In Business and Enterprise workspaces, an admin can import the marketplace for everyone instead: in **Admin** > **Plugins**, select **Add** > **Import marketplace** and enter `https://github.com/bitdriftlabs/bd-skills`. On chatgpt.com, [add the server URL directly](#direct-apps-and-ides) instead. For more details, see the [ChatGPT plugins documentation](https://learn.chatgpt.com/docs/plugins?surface=app){:target="_blank"}.

=== ":simple-claude: Claude"

    In Claude on the web or desktop:

    1. Open **Customize** > **Plugins**.
    2. Select **Add** > **Add marketplace**, then enter `bitdriftlabs/bd-skills`.
    3. Open **Discover**, select **bitdrift MCP**, then select **Add**.
    4. Open the plugin's **Connectors** tab, connect the bitdrift connector, and sign in with your bitdrift account.

    Plugins are available on paid plans. On Team and Enterprise plans, an owner first adds the bitdrift connector for your organization in **Organization settings** > **Connectors**. Members can add marketplaces themselves only while **User-created skills** is on in **Organization settings** > **Plugins & skills** > **Policy**. For more details, see the [Claude plugins documentation](https://support.claude.com/en/articles/13837440-use-plugins-in-claude){:target="_blank"} and [Manage plugins for your organization](https://claude.com/docs/plugins/admin){:target="_blank"}.

=== ":material-microsoft-visual-studio-code: VS Code"

    In VS Code with GitHub Copilot:

    1. Add the bitdrift marketplace to your user settings. Run **Preferences: Open User Settings (JSON)** from the Command Palette and add:

        ```json
        "chat.plugins.marketplaces": ["bitdriftlabs/bd-skills"]
        ```

    2. Open the Extensions view, search for `@agentPlugins`, and install `bitdrift-mcp`.
    3. Sign in with your bitdrift account when VS Code prompts you. The bitdrift tools are then available in Copilot Chat agent mode.

    If the plugin doesn't appear, check that the `chat.plugins.enabled` setting is on. VS Code also picks up plugins you install with Copilot CLI. Your organization's Copilot policies control whether you can use plugins and MCP servers. For more details, see the [VS Code agent plugins documentation](https://code.visualstudio.com/docs/agent-customization/agent-plugins){:target="_blank"}.

#### CLIs { #plugin-clis }

=== ":fontawesome-brands-openai: Codex"

    ```bash
    codex plugin marketplace add bitdriftlabs/bd-skills
    codex plugin add bitdrift-mcp@bitdrift
    ```

    Start a new session to use the plugin. For more details, see the [Codex plugins documentation](https://learn.chatgpt.com/docs/plugins?surface=cli){:target="_blank"}.

=== ":simple-claude: Claude Code"

    Run these commands in Claude Code:

    ```text
    /plugin marketplace add bitdriftlabs/bd-skills
    /plugin install bitdrift-mcp@bitdrift
    ```

    For more details, see the [Claude Code plugins documentation](https://code.claude.com/docs/en/discover-plugins){:target="_blank"}.

=== ":simple-githubcopilot: Copilot CLI"

    ```bash
    copilot plugin marketplace add bitdriftlabs/bd-skills
    copilot plugin install bitdrift-mcp@bitdrift
    ```

    For more details, see the [Copilot CLI plugins documentation](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing){:target="_blank"}.

### Direct MCP URL { #direct-mcp-url }

#### Apps and IDEs { #direct-apps-and-ides }

=== ":fontawesome-brands-openai: ChatGPT"

    In ChatGPT:

    1. Open **Plugins**, select **+**, then select **Add custom MCP server**.
    2. Enter `bitdrift` as the name, add a short description, and enter `https://mcp.bitdrift.ai/` as the URL under **Connection**.
    3. Choose **OAuth** authentication, review the warning, and select **I understand and want to continue**.
    4. Select **Create as a plugin** and sign in with your bitdrift account.

    Your account and workspace policies control whether you can add custom MCP servers. For more details, see the [ChatGPT MCP documentation](https://developers.openai.com/plugins/deploy/connect-chatgpt){:target="_blank"}.

    In the ChatGPT desktop app, you can also install the server as the `bitdrift-mcp` plugin. See [Plugin](#plugin).

=== ":simple-claude: Claude"

    In Claude on the web or desktop:

    1. Open **Customize** > **Connectors**.
    2. Select **+ Add**, then select **Add custom connector**.
    3. Enter `bitdrift` as the name and `https://mcp.bitdrift.ai/` as the URL, then select **Continue**.
    4. Review the detected authentication settings. Under **OAuth client**, keep **Use Claude's published identity (Recommended)**, then select **Continue**.
    5. Sign in with your bitdrift account.

    On Team and Enterprise plans, an owner adds the connector for your organization first; then select **Connect** next to it. For more details, see the [Claude custom connectors documentation](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp){:target="_blank"}.

    You can also install the server as the `bitdrift-mcp` plugin. See [Plugin](#plugin).

=== ":brands-cursor: Cursor"

    1. Open **Customize** from the sidebar, select **MCPs**, then select **New MCP Server**. Cursor opens your `~/.cursor/mcp.json` file.
    2. Add the bitdrift server and save the file. If the file already lists other servers, add only the `bitdrift` entry inside `mcpServers`.

        ```json
        {
          "mcpServers": {
            "bitdrift": {
              "url": "https://mcp.bitdrift.ai/"
            }
          }
        }
        ```

    3. Sign in with your bitdrift account when Cursor prompts you. **bitdrift** then appears under **Connected** in the MCPs list.

    You can also edit `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project) directly. For more details, see the [Cursor MCP documentation](https://cursor.com/docs/mcp){:target="_blank"}.

=== ":material-microsoft-visual-studio-code: VS Code"

    Add the server to `.vscode/mcp.json` in your workspace, or run **MCP: Add Server** from the Command Palette:

    ```json
    {
      "servers": {
        "bitdrift": {
          "type": "http",
          "url": "https://mcp.bitdrift.ai/"
        }
      }
    }
    ```

    Select **Start** above the server entry and sign in when prompted. The bitdrift tools are then available in Copilot Chat agent mode. For more details, see the [VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers){:target="_blank"}.

    You can also install the server as the `bitdrift-mcp` plugin. See [Plugin](#plugin).

=== ":simple-google: Antigravity"

    1. Open **Settings** at the bottom left, select **Customizations**, then select **Open MCP Config** under **Installed MCP Servers**. Antigravity opens your `~/.gemini/config/mcp_config.json` file.
    2. Add the bitdrift server and save the file. Antigravity uses `serverUrl` for remote servers. If the file already lists other servers, add only the `bitdrift` entry inside `mcpServers`.

        ```json
        {
          "mcpServers": {
            "bitdrift": {
              "serverUrl": "https://mcp.bitdrift.ai/"
            }
          }
        }
        ```

    3. Select **Authenticate** next to **bitdrift**. Until you sign in, Antigravity shows an "Unauthorized" error for the server.
    4. Sign in with your bitdrift account and select **Authorize**. Antigravity's page then shows an authorization code. Select **Copy to Clipboard**, then paste the code into Antigravity and submit it.

    The same file configures the Antigravity IDE and the Antigravity CLI, which signs in separately (see [CLIs](#direct-clis)). For more details, see the [Antigravity MCP documentation](https://antigravity.google/docs/mcp){:target="_blank"}.

=== ":material-ghost-outline: Kiro"

    1. Open the Kiro panel and select the **Open MCP Config** icon in the **MCP Servers** section, or run **Kiro: Open user MCP config (JSON)** from the Command Palette. Kiro opens your `~/.kiro/settings/mcp.json` file.
    2. Add the bitdrift server and save the file. If the file already lists other servers, add only the `bitdrift` entry inside `mcpServers`.

        ```json
        {
          "mcpServers": {
            "bitdrift": {
              "url": "https://mcp.bitdrift.ai/"
            }
          }
        }
        ```

    3. If **bitdrift** doesn't appear in **MCP Servers**, select **Enable All MCP Servers** in that section.
    4. Kiro doesn't start the sign-in on its own. In **MCP Servers**, choose **Reauthenticate** on **bitdrift**, select **Open**, and then select **Authorize** in your browser. **bitdrift** then shows as connected.

    Kiro waits about a minute for you to finish signing in, so sign in to bitdrift in your browser first. If it times out, choose **Reauthenticate** again. For more details, see the [Kiro MCP documentation](https://kiro.dev/docs/mcp/configuration/){:target="_blank"}.

#### CLIs { #direct-clis }

=== ":fontawesome-brands-openai: Codex"

    Add the server and sign in:

    ```bash
    codex mcp add bitdrift --url https://mcp.bitdrift.ai/
    codex mcp login bitdrift
    ```

    For more details, see the [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli){:target="_blank"}.

    You can also install the server as the `bitdrift-mcp` plugin. See [Plugin](#plugin).

=== ":simple-claude: Claude Code"

    Add the server:

    ```bash
    claude mcp add --transport http bitdrift https://mcp.bitdrift.ai/
    ```

    Then start Claude Code, run `/mcp`, select **bitdrift**, and choose **Authenticate**. For more details, see the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp){:target="_blank"}.

    You can also install the server as the `bitdrift-mcp` plugin. See [Plugin](#plugin).

=== ":simple-githubcopilot: Copilot CLI"

    Add the server:

    ```bash
    copilot mcp add --transport http bitdrift https://mcp.bitdrift.ai/
    ```

    Then start `copilot`. It opens your browser to sign in with your bitdrift account; select **Authorize**. Type `/mcp` to check that **bitdrift** is connected. For more details, see the [Copilot CLI MCP documentation](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers){:target="_blank"}.

    You can also install the server as the `bitdrift-mcp` plugin. See [Plugin](#plugin).

=== ":simple-googlegemini: Gemini CLI"

    Add the server:

    ```bash
    gemini mcp add --transport http bitdrift https://mcp.bitdrift.ai/
    ```

    Then start Gemini CLI and sign in with your bitdrift account when prompted. If you aren't prompted, run `/mcp auth bitdrift`. For more details, see the [Gemini CLI MCP documentation](https://geminicli.com/docs/tools/mcp-server/){:target="_blank"}.

=== ":simple-google: Antigravity CLI"

    1. Add the server to `~/.gemini/config/mcp_config.json` and save the file. Antigravity uses `serverUrl` for remote servers. If you already added bitdrift in the Antigravity app, skip this step, because the app and CLI share this file.

        ```json
        {
          "mcpServers": {
            "bitdrift": {
              "serverUrl": "https://mcp.bitdrift.ai/"
            }
          }
        }
        ```

    2. Start `agy`, type `/mcp`, select **bitdrift**, and choose to authenticate.
    3. Sign in with your bitdrift account in your browser and select **Authorize**. Copy the authorization code that Antigravity shows, then paste it into the terminal.

    The CLI signs in separately from the Antigravity app. For more details, see the [Antigravity MCP documentation](https://antigravity.google/docs/mcp){:target="_blank"}.

=== ":material-ghost-outline: Kiro CLI"

    1. Add the server to `~/.kiro/settings/mcp.json` and save the file. If you already added bitdrift in the Kiro IDE, skip this step, because the IDE and CLI share this file.

        ```json
        {
          "mcpServers": {
            "bitdrift": {
              "url": "https://mcp.bitdrift.ai/"
            }
          }
        }
        ```

    2. Start `kiro-cli chat`. When it shows that bitdrift requires OAuth, press **Ctrl+Y** and select **Authorize** in your browser.
    3. Type `/mcp` to check that **bitdrift** is running. To sign in again later, select **bitdrift** in `/mcp` and press **Ctrl+A**.

    The CLI signs in separately from the Kiro IDE. For more details, see the [Kiro MCP documentation](https://kiro.dev/docs/mcp/configuration/){:target="_blank"}.

=== ":material-console: OpenCode"

    Add the server to `~/.config/opencode/opencode.json` (all projects) or `opencode.json` in your project:

    ```json
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "bitdrift": {
          "type": "remote",
          "url": "https://mcp.bitdrift.ai/"
        }
      }
    }
    ```

    OpenCode asks you to sign in the first time it uses the server. If it doesn't, run `opencode mcp auth bitdrift`. For more details, see the [OpenCode MCP documentation](https://opencode.ai/docs/mcp-servers){:target="_blank"}.

#### Other clients { #direct-other-clients }

Any MCP client that supports streamable HTTP and [OAuth sign-in](#supported-clients) can connect. Add a server with the URL `https://mcp.bitdrift.ai/` and follow your client's sign-in flow. Clients that can't sign in with OAuth can use an [access token](#access-tokens) instead.

### Verify the connection

Ask your agent a question that needs bitdrift data, for example:

> *"Which bitdrift apps can you see in the last week?"*

The agent should call bitdrift tools and answer with data from your account.

## Supported client authentication methods { #supported-clients }

The server supports MCP clients that sign in with OAuth, using either of these client registration methods from the [MCP specification](https://modelcontextprotocol.io/specification/latest/basic/authorization){:target="_blank"}:

- **Client ID Metadata Documents (CIMD)**, the method the specification recommends.
- **Dynamic Client Registration (DCR)**, for clients that don't support CIMD yet.

Either way, you sign in with your bitdrift account without registering an app or creating a key.

The [Quickstart](#quickstart) has step-by-step instructions for common apps, IDEs, and CLIs. Other clients can connect if they support these OAuth methods for connecting to remote MCP servers. If yours doesn't, connect with an [access token](#access-tokens) or use the [CLI + Agent Skills](skills.md) instead.

### Access tokens { #access-tokens }

<img alt="bd CLI Support" src="https://img.shields.io/badge/bd%20CLI-0.2.46-006C9C">

For clients that can't sign in with OAuth, such as scripts, CI jobs, or headless agents, send a personal access token or organization token as a bearer token. Create one with the [`bd` CLI](../cli/quickstart.md) after signing in with `bd auth`, granting only the permissions your agent needs:

- **Organization token:** for CI jobs and agents shared by a team. It acts as itself, and what it creates is attributed to the token's name, so it keeps working when the person who set it up leaves. Creating one requires the Admin role.

    ```sh
    bd key create --name ci-agent org --permissions workflow-read --permissions issue-read
    ```

- **Personal access token:** for your own headless agents. It acts as you, limited to both its own permissions and the ones you still hold.

    ```sh
    bd key create --name my-agent personal --permissions workflow-read --permissions issue-read
    ```

Then configure your client to send the token in this header to `https://mcp.bitdrift.ai/`:

```
Authorization: Bearer <token>
```

Revoke a token at any time with `bd key revoke <id>`. Legacy API keys don't work with the MCP server. See [Personal access tokens and organization tokens](../api-guide/calling-the-api.md#access-tokens) for lifetimes and rotation.

## What your agent can do

See [What your agent can do](../ai.md#what-your-agent-can-do) and [example prompts](../ai.md#example-prompts) on the overview page. Your client lists the server's current tools when it connects.

### Usage guides

The server includes usage guides that teach your agent how to approach common tasks, such as investigating issues and sessions, reading charts, and authoring workflows. Clients that support MCP resources can read them directly; other clients read them through the guide tools. You don't need to install anything else for your agent to use them. They cover the same ground that the [`bd-cli`](skills.md#bd-cli) skill covers for the CLI.

### Interactive charts and session replay

In clients that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview){:target="_blank"}, your agent can show workflow charts and [session replay](../product/timeline/session-replay.md) frames as interactive components directly in the conversation. In other clients, the agent describes the data in text.

## Other bitdrift agent skills { #skills-with-the-mcp-server }

The `bitdrift-sdk` plugin is optional and separate from the MCP server. Its skills work on your app's code and don't need the `bd` CLI, so you can install them alongside the server:

- [`bd-instrumentation`](skills.md#bd-instrumentation) adds and configures the Capture SDK in your iOS, Android, or React Native app.
- [`bd-docs`](skills.md#bd-docs) searches this documentation to answer questions about bitdrift.

See [Install the other bitdrift agent skills](skills.md#install-the-other-bitdrift-agent-skills) for install steps.

Don't install the `bitdrift-cli` plugin or the [`bd-cli`](skills.md#bd-cli) skill with the MCP server. They cover the same tasks through the `bd` CLI, so your agent would have two tools for the same job. The [`bd-cuj`](skills.md#bd-cuj) skill runs `bd` commands too, so it needs the CLI.

## Updating

New tools and usage guides ship on the server, so there is nothing to update locally.
