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

# Connect to Honeycomb MCP

> Connect your AI agent to the Honeycomb MCP Server.

Connect Honeycomb to any AI agent that supports the Model Context Protocol (MCP) so it can query your telemetry, investigate issues, and answer questions using your live Honeycomb data.
This guide covers the fastest way to connect, manual configuration for specific clients, and authentication with an API key.

<Tip>
  If you need to get data into Honeycomb using sample data, real instrumentation, or connecting to an existing pipeline, start with [Send data with AI](/send-data/ai) instead.
</Tip>

## Before you begin

Make sure that:

* Your Honeycomb team has [enabled Honeycomb Intelligence](/configure/teams/manage-behavior#enable-honeycomb-intelligence).
* Your AI agent supports remote MCP servers or plugins.

## Put your agent to work

Run the prompt associated with your region in your AI agent:

<Tabs>
  <Tab title="US">
    <Prompt description="Connect to the Honeycomb MCP server (US)" icon="sparkle">
      Add the Honeycomb MCP server at [https://mcp.honeycomb.io/mcp](https://mcp.honeycomb.io/mcp) and authenticate with OAuth.
    </Prompt>
  </Tab>

  <Tab title="EU">
    <Prompt description="Connect to the Honeycomb MCP server (EU)" icon="sparkle">
      Add the Honeycomb MCP server at [https://mcp.eu1.honeycomb.io/mcp](https://mcp.eu1.honeycomb.io/mcp) and authenticate with OAuth.
    </Prompt>
  </Tab>
</Tabs>

Once your agent authenticates, it can query your telemetry, investigate issues, and answer questions using your live Honeycomb data.
For the list of tools that Honeycomb MCP exposes to your agent, visit the [MCP Tools Reference](/integrations/mcp/tools).

## Connect manually

For step-by-step configuration instructions, select your client:

<div className="hny-client-tabs">
  <Tabs>
    <Tab title="Amazon Q">
      Connect Amazon Q Developer to Honeycomb MCP using the qchat CLI:

      1. Run the command associated with your region in your terminal:

               <Tabs>
                 <Tab title="US">
                   ```bash wrap theme={}
                   qchat mcp add --name honeycomb --command npx --args mcp-remote,https://mcp.honeycomb.io/mcp
                   ```
                 </Tab>

                 <Tab title="EU">
                   ```bash wrap theme={}
                   qchat mcp add --name honeycomb --command npx --args mcp-remote,https://mcp.eu1.honeycomb.io/mcp
                   ```
                 </Tab>
               </Tabs>

      2. Run any [MCP tool](/integrations/mcp/tools).
         Authenticate and grant the requested permissions to finish connecting.

      <Tip>
        Want your agent to send data too?
        [Send data with AI](/send-data/ai) walks through running guided onboarding to help you instrument your application.
      </Tip>
    </Tab>

    <Tab title="Auggie CLI">
      Connect Augment (Auggie CLI) to Honeycomb MCP by installing the Honeycomb plugin:

      <Steps>
        <Step title="Add the Honeycomb agent skills as a plugin source">
          Run this in your terminal:

          ```bash theme={}
          auggie plugin marketplace add honeycombio/agent-skill
          ```

          <Tip>
            To check out the Honeycomb agent skills, [visit the agent skills repo](https://github.com/honeycombio/agent-skill).
          </Tip>
        </Step>

        <Step title="Install the Honeycomb plugin">
          Run this in your terminal:

          ```bash theme={}
          auggie plugin install honeycomb
          ```
        </Step>

        <Step title="Set up the Honeycomb MCP">
          Run this prompt in Auggie and authenticate with Honeycomb when asked:

          <Prompt description="Set up Honeycomb" icon="sparkle">
            /honeycomb-setup
          </Prompt>

          Your agent connects to Honeycomb MCP: sets your region, authenticates, and verifies access.
        </Step>
      </Steps>

      <Tip>
        Want your agent to send data too?
        [Send data with AI](/send-data/ai) walks through installing Honeycomb's agent skills and running guided onboarding to help you instrument your application.
      </Tip>
    </Tab>

    <Tab title="ChatGPT">
      Connect ChatGPT to Honeycomb MCP by installing the Honeycomb app from ChatGPT's app directory:

      1. [Go to the Honeycomb plugin page](https://chatgpt.com/plugins/plugin_asdk_app_6a51b29fa2d48191b215ff28f9a64fb4).
      2. Select **Install plugin**.
      3. When prompted, sign in to Honeycomb to finish authentication.

      <Tip>
        Want your agent to send data too?
        [Send data with AI](/send-data/ai) walks through installing Honeycomb's agent skills and running guided onboarding to help you instrument your application.
      </Tip>
    </Tab>

    <Tab title="Claude Code">
      Connect Claude Code to Honeycomb MCP by installing the Honeycomb plugin:

      <Steps>
        <Step title="Install Honeycomb as a Claude Code plugin">
          Run this in your terminal:

          ```bash theme={}
          claude plugin marketplace add honeycombio/agent-skill
          claude plugin install honeycomb
          ```
        </Step>

        <Step title="Set up the Honeycomb MCP">
          Run this prompt in Claude Code and authenticate with Honeycomb when asked:

          <Prompt description="Set up Honeycomb" icon="sparkle">
            /honeycomb-setup
          </Prompt>

          Your agent connects to Honeycomb MCP: sets your region, authenticates, and verifies access.
        </Step>
      </Steps>

      <Tip>
        Want your agent to send data too?
        [Send data with AI](/send-data/ai) walks through running guided onboarding to help you instrument your application.
      </Tip>

      <Accordion title="Set up Claude Code manually">
        <Steps>
          <Step title="Add the Honeycomb MCP">
            Run the command associated with your region in your terminal:

            <Tabs>
              <Tab title="US">
                ```bash wrap theme={}
                claude mcp add honeycomb --transport http https://mcp.honeycomb.io/mcp
                ```
              </Tab>

              <Tab title="EU">
                ```bash wrap theme={}
                claude mcp add honeycomb --transport http https://mcp.eu1.honeycomb.io/mcp
                ```
              </Tab>
            </Tabs>
          </Step>

          <Step title="Add the Honeycomb skills">
            Download the skills folder from the [Honeycomb agent-skill repo](https://github.com/honeycombio/agent-skill/tree/main/honeycomb/skills) and copy it into your skills directory:

            ```bash theme={}
              git clone https://github.com/honeycombio/agent-skill.git /tmp/agent-skill-temp
              cp -r /tmp/agent-skill-temp/honeycomb/skills/* ~/.claude/skills/
              rm -rf /tmp/agent-skill-temp
            ```

            For details on skill locations and scope, see [Claude Code's Agent Skills documentation](https://docs.claude.com/en/docs/claude-code/skills).
          </Step>

          <Step title="Set up the MCP">
            Run this prompt in Claude Code and authenticate with Honeycomb when asked:

            <Prompt description="Set up Honeycomb" icon="sparkle">
              /honeycomb-setup
            </Prompt>

            Your agent connects to Honeycomb MCP: sets your region, authenticates, and verifies access.
          </Step>
        </Steps>

        <Tip>
          Want your agent to send data too?
          [Send data with AI](/send-data/ai) walks through running guided onboarding to help you instrument your application.
        </Tip>
      </Accordion>
    </Tab>

    <Tab title="Claude Desktop">
      Connect Claude Desktop to Honeycomb MCP using the Honeycomb connector:

      1. Select **Customize** > **Connectors**.
      2. Select **Add** > **Browse Connectors**.
      3. Search for `Honeycomb` to go to the [Honeycomb connector](https://claude.ai/directory/connectors/honeycomb) page.
      4. Select the `+` on the Honeycomb connector to add it.
      5. When prompted, sign in to Honeycomb and authorize the application.
         If no browser window opens to prompt authentication over OAuth, fully quit and reopen Claude Desktop.

      <Tip>
        Want your agent to send data too?
        [Send data with AI](/send-data/ai) walks through installing Honeycomb's agent skills and running guided onboarding to help you instrument your application.
      </Tip>
    </Tab>

    <Tab title="Codex">
      Connect OpenAI Codex to Honeycomb MCP by installing Honeycomb as a plugin:

      <Steps>
        <Step title="Install the Honeycomb plugin">
          Run this in your terminal:

          ```bash theme={}
          codex plugin marketplace add honeycombio/agent-skill
          codex plugin add honeycomb@honeycomb-plugins
          ```
        </Step>

        <Step title="Load the plugin">
          Restart Codex to load the plugin.
          This also configures the Honeycomb MCP server for you.
        </Step>
      </Steps>

      <Tip>
        Want your agent to send data too?
        [Send data with AI](/send-data/ai) walks through running guided onboarding to help you instrument your application.
      </Tip>
    </Tab>

    <Tab title="Copilot">
      Connect GitHub Copilot to Honeycomb MCP by installing the Honeycomb plugin:

      <Steps>
        <Step title="Install Honeycomb as a Copilot plugin">
          Run this in your terminal:

          ```bash theme={}
          copilot plugin install honeycombio/agent-skill:honeycomb
          ```
        </Step>

        <Step title="Set up the Honeycomb MCP">
          Run this prompt in Copilot and authenticate with Honeycomb when asked:

          <Prompt description="Set up Honeycomb" icon="sparkle">
            /honeycomb-setup
          </Prompt>

          Your agent connects to Honeycomb MCP: sets your region, authenticates, and verifies access.
        </Step>
      </Steps>

      <Tip>
        Want your agent to send data too?
        [Send data with AI](/send-data/ai) walks through running guided onboarding to help you instrument your application.
      </Tip>
    </Tab>

    <Tab title="Cursor">
      Connect Cursor to Honeycomb MCP using this one-click install link: [Add Honeycomb to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=honeycomb\&config=eyJ1cmwiOiJodHRwczovL21jcC5ob25leWNvbWIuaW8vbWNwIn0=)

      <Tip>
        Want your agent to send data too?
        [Send data with AI](/send-data/ai) walks through installing Honeycomb's agent skills and running guided onboarding to help you instrument your application.
      </Tip>

      <Accordion title="Set up Cursor manually">
        <Steps>
          <Step title="Add the Honeycomb MCP">
            1. Open Cursor and navigate to **Preferences** > **Cursor Settings** > **Customize**.

            2. Select the **MCP** view.

            3. Select **New MCP Server**.

            4. Update `mcp.json` with the configuration for your region:

                           <Tabs>
                             <Tab title="US">
                               ```json theme={}
                               {
                                 "mcpServers": {
                                   "honeycomb": {
                                     "url": "https://mcp.honeycomb.io/mcp"
                                   }
                                 }
                               }
                               ```
                             </Tab>

                             <Tab title="EU">
                               ```json theme={}
                               {
                                 "mcpServers": {
                                   "honeycomb": {
                                     "url": "https://mcp.eu1.honeycomb.io/mcp"
                                   }
                                 }
                               }
                               ```
                             </Tab>
                           </Tabs>

            5. Save the configuration file and restart Cursor.
          </Step>

          <Step title="Authenticate with the Honeycomb MCP">
            Run any [MCP tool](/integrations/mcp/tools).
            Honeycomb opens a browser window to authenticate.
            Grant the requested permissions to finish connecting.
          </Step>
        </Steps>

        <Tip>
          Want your agent to send data too?
          [Send data with AI](/send-data/ai) walks through installing Honeycomb's agent skills and running guided onboarding to help you instrument your application.
        </Tip>
      </Accordion>
    </Tab>

    <Tab title="VS Code">
      Connect VS Code (with GitHub Copilot) to Honeycomb MCP with this one-click install link: [Add Honeycomb to VS Code](vscode:mcp/install?%7B%22name%22%3A%22honeycomb%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.honeycomb.io%2Fmcp%22%7D)

      <Tip>
        Want your agent to send data too?
        [Send data with AI](/send-data/ai) walks through installing Honeycomb's agent skills and running guided onboarding to help you instrument your application.
      </Tip>
    </Tab>
  </Tabs>
</div>

## Authenticate with an API key

If you are building autonomous or unattended agents and cannot use OAuth, then you can authenticate with an API key.
Only team owners can generate an API key.

<Note>
  Prefer OAuth in most use cases.
  Use an API key only when your agent cannot support interactive login.
</Note>

<Steps titleSize="h3">
  <Step title="Generate an API key in Honeycomb">
    1. Log in to your Honeycomb account.
    2. Navigate to **Account** > **Team Settings** > **API Keys**.
    3. Select **Create Management API Key**.
    4. Name your key (for example, "MCP Integration").
    5. Choose the **Model Context Protocol** and **Environments** scopes, then grant permissions:
       * **Read**: Required for all Honeycomb MCP operations.
         Be sure to grant read for both MCP and Environments.
       * **Write**: Required for tools that create or update Honeycomb resources, including Boards, Triggers, SLOs, notification/alert recipients, and Canvas investigations.
         To explore the complete list of write tools, visit the [MCP Tools Reference](/integrations/mcp/tools/#required-scopes-for-write-tools).
    6. Copy the **Key ID** and **Key Secret**, and store them somewhere safe.
       You will need them later, and you won't be able to see them again.
  </Step>

  <Step title="Add your API key to your agent">
    The exact configuration process varies by agent, but here is an example configuration `mcp.json` snippet used by agents like Claude Code or Cursor:

    <Tip>
      Be sure to use the appropriate endpoint for your region, and replace `KEY_ID` and `SECRET_KEY` with your actual key values.
    </Tip>

    ```json theme={}
    {
      "mcpServers": {
        "honeycomb": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://mcp.honeycomb.io/mcp",
            "--header",
            "Authorization: Bearer $HONEYCOMB_API_KEY"
          ],
          "env": {
            "HONEYCOMB_API_KEY": "<KEY_ID>:<SECRET_KEY>"
          }
        }
      }
    }
    ```

    <Info>
      Pay attention to formatting, including spacing and colon (`:`) characters.

      If your tool cannot parse the `Authorization` header correctly, try putting the `Bearer` prefix directly in the environment variable:
      `"HONEYCOMB_API_KEY": "Bearer KEY_ID:SECRET_KEY"`.
    </Info>

    As a security best practice, make sure that keys being used for MCP integrations do not carry any other scopes, and that you do not commit them to source control.
  </Step>

  <Step title="Confirm the connection">
    Once connected, test by asking your agent to list available tools or fetch available teams and environments.
    You should get results if your key and permissions are set up correctly.
  </Step>
</Steps>

## Limit the tools your agent loads

A smaller tool list can help your agent choose the right tool and use less of its context.
By default, your agent loads every Honeycomb MCP tool and prompt.
To load only part of them, configure your AI tool to send the `X-MCP-Toolset` header with each request to Honeycomb MCP.

| Value | What your agent loads |
| - | - |
| `all` | Every tool and prompt available to you. This is the default. |
| `query` | Tools for querying and managing your telemetry, including Boards, Triggers, and SLOs. Includes prompts. |
| `canvas` | Only the tools for working with Canvas. Doesn't include prompts or query tools. |

The header limits which tools your agent loads but doesn't grant access.
Your scopes and plan still control which tools are available.
If the header has an unrecognized or empty value, Honeycomb MCP rejects each request that includes it, so your agent can't use Honeycomb MCP until you correct or remove the header.

## Next steps

Continue your MCP journey:

* [Example Use Cases](/integrations/mcp/use-cases): Explore real-world use cases and tips for working with Honeycomb via MCP.
* [Tools Reference](/integrations/mcp/tools): Learn about the tools Honeycomb MCP exposes to AI agents.

- [MCP Prompts Reference](/integrations/mcp/prompts/): Run pre-written workflows, like guided onboarding, from your AI agent.

* [Troubleshooting](/integrations/mcp/troubleshooting): Fix common MCP configuration and connection issues.