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

# Honeycomb

> Connect Honeycomb to CloudThinker with OAuth for trace queries, BubbleUp root-cause analysis, and approval-gated board and trigger changes

Connect your Honeycomb team to let [Alex](/guide/agents/alex) (Cloud Engineer) query traces, rank failing endpoints, run BubbleUp to find what changed, and follow a trace waterfall to the span that failed.

Honeycomb authenticates with **OAuth** through its hosted MCP server, so there is no API key to create and no credential to paste into CloudThinker.

## Prerequisites

* A **Honeycomb account** with access to the team you want CloudThinker to read.
* Permission to authorize CloudThinker during Honeycomb's OAuth flow.
* At least one **environment with a dataset receiving telemetry**. Every query tool needs a dataset; an environment with none means the account sends no telemetry, not a healthy zero.

<Info>
  CloudThinker connects to Honeycomb's US endpoint, `https://mcp.honeycomb.io/mcp`. The EU endpoint is not selectable, so an EU-only team cannot connect yet.
</Info>

## Setup

<Steps>
  <Step title="Open the connection">
    Go to **Connections → Honeycomb** in your CloudThinker workspace.
  </Step>

  <Step title="Start the OAuth flow">
    Click **Connect**. CloudThinker opens Honeycomb's authorization page.
  </Step>

  <Step title="Authorize CloudThinker">
    Sign in to the Honeycomb account that can reach the team you want to use, then approve access.
  </Step>

  <Step title="Return to CloudThinker">
    Honeycomb sends you back and CloudThinker stores the tokens. The connection shows a **Connected** status.
  </Step>
</Steps>

## Connection details

Honeycomb uses OAuth, so there are no fields to fill in. CloudThinker stores the access and refresh tokens after the flow completes and refreshes them without asking you again.

| Field            | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| **OAuth tokens** | Issued by Honeycomb and stored automatically; no manual entry required |
| **Endpoint**     | `https://mcp.honeycomb.io/mcp`, Honeycomb's hosted MCP server          |

## Required permissions

CloudThinker inherits whatever the authorizing Honeycomb account can reach. The authorization grants two scopes:

| Scope       | What it covers                                                                     |
| ----------- | ---------------------------------------------------------------------------------- |
| `mcp:read`  | Environments, datasets, columns, queries, traces, triggers, boards, and recipients |
| `mcp:write` | Creating and updating boards, triggers, SLOs, markers, and recipients              |

<Tip>
  Authorize with an account scoped to the team you want the agent to see. CloudThinker cannot narrow the grant below what that account already has.
</Tip>

## Agent capabilities

Once connected, Alex can:

| Capability                 | Description                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Environment discovery**  | Name the team, list environments and datasets, and report whether triggers, boards, and recipients exist |
| **Service health**         | Rank endpoints by failing span count and error rate, with p95 latency                                    |
| **Root-cause analysis**    | Run BubbleUp to find the dimension that separates failing spans from healthy ones                        |
| **Trace investigation**    | List spans, open span details, and follow a trace waterfall to the failure                               |
| **Alerting review**        | Read triggers, SLOs, boards, and notification recipients                                                 |
| **Approval-gated changes** | Create or update a board, trigger, SLO, marker, or recipient after you approve the exact inputs          |

### Verify the connection

```text theme={null}
@alex #report summarize my Honeycomb setup: team, environments, datasets, and whether triggers exist
```

### Example prompts

```text theme={null}
@alex which endpoint is in the worst shape right now
@alex why is POST /checkout failing and #report the dimension that changed
@alex show me the trace waterfall for the slowest checkout request
```

## Writes are permanent

Honeycomb's MCP server exposes no delete tool. A board, trigger, SLO, marker, or recipient the agent creates cannot be removed from CloudThinker; you remove it in Honeycomb.

Every write is therefore gated twice. The agent states the effect and shows the exact inputs, and the change runs only after you [approve](/guide/approval) it in that turn.

<Warning>
  Approve a create only when you want the object to exist for good. There is no undo path through CloudThinker.
</Warning>

## Troubleshooting

<Accordion title="The OAuth flow does not complete">
  Your browser may be signed in to a different Honeycomb account. Sign in to the intended account, then start the Honeycomb connection again.
</Accordion>

<Accordion title="Every call fails with an authentication error">
  The stored tokens are no longer valid, usually because the authorization was revoked in Honeycomb. Remove the connection and reconnect.
</Accordion>

<Accordion title="The agent reports no datasets">
  Queries need a dataset in a queryable environment. Confirm the environment is receiving telemetry in Honeycomb; an environment with no dataset cannot answer a query, a BubbleUp, or a trace question.
</Accordion>

<Accordion title="The agent skips one of my environments">
  `$activity-log$` is Honeycomb's own audit environment. It appears in the environment list, but every scoped call rejects it, so CloudThinker skips it on purpose.
</Accordion>

<Accordion title="A create was refused">
  Creating a board, trigger, SLO, marker, or recipient needs your approval in the same turn. Answer the approval prompt while it is open; a new turn asks again.
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **No result links in chat** — Honeycomb signs its query-result and trace-result download URLs. CloudThinker shares the human permalink instead, so a copied message never carries a token that grants result access.
- **Reconnect to switch teams** — remove the existing connection before authorizing a different Honeycomb account.

## Related

<CardGroup cols={2}>
  <Card title="Alex Agent" icon="cloud" href="/guide/agents/alex">
    Cloud and observability investigation agent
  </Card>

  <Card title="Approvals" icon="shield-check" href="/guide/approval">
    How CloudThinker gates a write behind your confirmation
  </Card>
</CardGroup>