Honeycomb gives an agent a hosted MCP server built for investigation and a REST API that carries events, queries and configuration. The MCP server is not a thin wrapper: it exposes BubbleUp, trace waterfalls and raw rows the REST API never did, while running a query over the API is an Enterprise feature. This guide compares what each path lets an SRE agent do, the OAuth grants and static keys each one puts you on, and how to run either across many customer teams in production.
Your agent sits next to production. It needs to answer "why did checkout get slow after the 14:05 deploy," pull the trace a customer pasted into a support ticket, mark every deploy on the charts so the next investigation starts with context, or set up the same SLOs and triggers for every new service a customer ships. Honeycomb ships a hosted MCP server built for exactly that kind of investigation, and a REST API that has carried Honeycomb's events, queries, and configuration for years. They share a team, environments, and datasets. They diverge on what an agent can query, which plan it needs, and whose identity every call runs under. Here's how to pick.
The Honeycomb MCP server is a remote Model Context Protocol (MCP) server that Honeycomb hosts at https://mcp.honeycomb.io/mcp (US) and https://mcp.eu1.honeycomb.io/mcp (EU) over Streamable HTTP (configuration guide). Honeycomb announced general availability on September 9, 2025, with query parity with the UI, BubbleUp, heatmaps and histograms, board creation, and Service Map support, and said MCP "is available to all of our accounts at no additional charge." The prerequisite is that the team has enabled Honeycomb Intelligence; without it, clients report "No tools found or access denied."
Connecting Claude Code is one line: claude mcp add honeycomb --transport http https://mcp.honeycomb.io/mcp. Honeycomb also ships plugins or one-click installs for Claude Desktop, ChatGPT, Cursor, VS Code, GitHub Copilot, Codex, Amazon Q, and Auggie.
The tools reference lists 34 tools in 12 groups: workspace discovery (get_workspace_context, get_environment, get_dataset, get_dataset_columns), query and analysis (run_query, get_query_results, find_queries, find_columns, run_bubbleup), traces (get_trace, list_spans, get_span_details), boards, triggers, SLOs, recipients, semantic conventions, AI conversation analysis (list_aiconversations, get_aiconversation), Canvas (canvas_agent_invoke, canvas_agent_poll_response), and a few utilities. Nine tools write. An X-MCP-Toolset header narrows what a client loads to query or canvas.
Before the hosted server, Honeycomb published a local stdio server, honeycombio/honeycomb-mcp, which read API keys from HONEYCOMB_API_KEY and was available only to Enterprise customers. Its README now says it "is deprecated. Please migrate to the hosted Honeycomb Model Context Protocol (MCP) solution."
The Honeycomb API is REST at https://api.honeycomb.io (US) and https://api.eu1.honeycomb.io (EU). Its reference groups it into Auth, Boards, Burn Alerts, Calculated Fields, Columns, Datasets, Dataset Definitions, Events, Environments, Key Management, Markers, Marker Settings, Queries, Query Annotations, Query Data, Recipients, Reporting, Service Maps, SLOs, Triggers, and Anomaly Detection. Honeycomb's Terraform provider and OpenTelemetry SDKs sit on top of it.
Auth is three kinds of API key (authentication):
Only Team Owners can create keys (manage API keys). There is no OAuth flow on the REST API.
The surprise is the first row. Honeycomb's MCP server is not a thin wrapper over the public API. It exposes investigation features the REST API never did: BubbleUp, trace waterfalls, raw rows, intent-based column search, and Canvas. For a team that isn't on Enterprise, MCP is the only programmatic way to run a query at all, because the Configuration key's Run queries permission is Enterprise only.
The API wins on everything around the investigation: getting data in, keeping configuration consistent across environments, and managing the keys themselves. get_service_map exists on MCP, but it is marked Enterprise and limited to 10 calls per minute, and the Service Maps API carries the same Enterprise requirement.
"Why did checkout latency spike at 14:00" on the raw API means creating a query spec with POST /1/queries/{datasetSlug}, creating a result with POST /1/query_results/{datasetSlug}, polling GET /1/query_results/{datasetSlug}/{id} until complete is true, and then explaining the spike yourself, because there is no BubbleUp endpoint. Your code also has to know the column is duration_ms and not http.server.duration.
On MCP, the model calls find_columns with "request duration," runs a HEATMAP with run_query, hands the query_pk to run_bubbleup with the spike selected, and drills into an example with get_trace. Each tool description tells the model what to pair it with, and results come back as Markdown tables, ASCII time series, and trace links already scoped to the query's time range. Writing the schema is the hard part. Not the API call.
The tradeoff is that Honeycomb owns the surface. Honeycomb's reference says rate limits "may change," and the tool lists already differ between sources: Honeycomb's reference includes SLO, service map, and anomaly profile tools, while Scalekit's catalog of the same server includes honeycombmcp_create_marker, honeycombmcp_get_signals, and honeycombmcp_semconv. An agent tuned against today's tool names can change behavior without a release on your side.
On the MCP path, OAuth is the default and Honeycomb says to "prefer OAuth in most use cases." The user signs in to Honeycomb in a browser and grants scopes: mcp:read for everything, mcp:write for the nine write tools. If an agent can't create a board or trigger, Honeycomb's fix is to re-authorize and grant write during consent. The grant carries the user's Honeycomb role. Honeycomb exposes the Activity Log environment over MCP only to Team Owners, so an engineer's agent cannot read it. What the user can't do, the agent can't do.
A single OAuth grant can cover more than one Honeycomb team. Every tool accepts an optional team input, "only needed when your authorization covers multiple teams." That matters for a consultant or platform engineer who belongs to several customers' teams: the tenant boundary is a parameter the model fills in.
For unattended agents, the MCP server also accepts a Management API key with the Model Context Protocol and Environments scopes, sent as Authorization: Bearer KEY_ID:SECRET. Only Team Owners can create it, Honeycomb says it should carry no other scopes, and the secret is shown once.
Two operational details come with OAuth. Honeycomb's troubleshooting guide says MCP agent sessions "may time out after 24 hours," and OAuth rate limits "are per-user, shared across all sessions for that user." Ten agent runs for the same engineer split one 50-calls-per-minute default.
On the direct API path, every credential is a static key that belongs to an environment or a team, not to a person. A Configuration key with Run queries, Triggers, and Boards enabled acts the same no matter which of your users the agent is serving. Honeycomb's docs describe no automatic expiry; rotation is something you record in the key's description and run yourself. Configuration key secrets can be viewed again in the UI at any time, while Ingest key secrets are shown only at creation. GET /1/auth tells you what a key is: its type, team, environment, and a flag for each permission.
In a multi-tenant B2B agent, MCP's OAuth flow gives you a token per user and the direct API gives you a key per environment per customer. In neither case does the path itself solve storage, rotation, or revocation; those are infrastructure problems regardless of which path you choose.
Honeycomb sharpens the boundary in two ways. On the API path, a key's scope is an environment, so an agent serving five engineers at one customer acts as one identity in production, and Honeycomb can't tell which engineer asked. On the MCP path, a grant can span several teams, so a wrong team value is a cross-tenant query, not an error.
Recommended reading: OAuth vs API keys for AI agents
On the MCP path, Honeycomb hosts the server, owns the tool schemas, and enforces the user's role and scopes. You own each user's OAuth session if your product is the MCP client, or a Management key per customer team if your agent runs headless. You also own the rate budget. Honeycomb publishes per-tool limits: 100 calls per minute for run_query and get_trace, 50 for run_bubbleup, list_spans, and get_span_details, 20 for create_trigger, create_slo, create_recipient, and canvas_agent_invoke. A model that loops on list_spans while it guesses span names can throttle the person it is helping.
Some tools are long-running. canvas_agent_invoke starts an investigation and canvas_agent_poll_response waits up to 50 seconds per call, returning running until it finishes. Your loop needs to treat that as normal, not as a failure.
On the API path, you own the query state machine, retries, and the keys. Honeycomb's rate limit docs describe a general limit that varies by policy (the example is 100 requests per 60 seconds), 10 per minute for creating query results, and 1 per minute when the query uses relational fields. Most 429 responses carry Retry-After and a RateLimit header with remaining and reset, but the Events, Batch Events, and Query Data APIs don't send Retry-After, so your backoff can't depend on it. v1 endpoints return RFC 7807 problem details on errors; v2 endpoints return JSON:API errors with codes like rate-limited/may-retry.
For events, Honeycomb's webhook recipients fire on triggers, SLO burn alerts, and Anomaly Detection. Each delivery can carry a shared secret in X-Honeycomb-Webhook-Token, up to five custom headers, and an X-Honeycomb-Webhook-Delivery-ID that stays the same across retries. Honeycomb expects a response within 15 seconds and retries only certain failures. A webhook is how a headless agent learns an alert fired, on either path; the MCP server has no subscription.
Use Honeycomb MCP when:
Use the Honeycomb API when:
Both paths hand you a Honeycomb credential. Neither hands you a vault. A multi-tenant SRE agent serving 40 customer teams with 8 engineers each holds 320 OAuth grants on the MCP path, each one expiring into a re-authorization if the session times out, and some of them spanning more than one customer's team. On the API path it holds at least 80 Configuration keys, one each for production and staging per customer, plus a Management key per customer if it provisions anything. Those keys don't expire, every one acts as no particular person, and every one has to be stored encrypted, kept out of logs and LLM context, and deleted when a customer churns.
The tempting shortcut is one Management key per customer, created by a Team Owner, wired into the agent for every engineer at that customer. Fewer secrets, larger blast radius per secret: that key reaches every environment in the team, and every engineer's request runs with the owner's reach.
Scalekit's honeycombmcp connector handles the Honeycomb OAuth flow, stores each user's tokens in the token vault, and refreshes them, so the MCP vs API decision doesn't change your auth infrastructure. Your agent passes an identifier; credentials never touch the agent runtime or the LLM context.
Recommended reading: why a token vault matters for AI agent workflows
Scalekit's honeycombmcp connector proxies Honeycomb's own MCP server. It exposes 31 tools: 23 read-only, 6 write, and 2 destructive (honeycombmcp_update_board and honeycombmcp_update_trigger, which edit existing resources in place). The core set for investigation:
The connector authenticates with OAuth 2.1, and each user signs in to Honeycomb once.
In the Scalekit dashboard, go to AgentKit > Connections, create a Honeycomb MCP connection, and copy its redirect URI. Scalekit's connector docs have you register an OAuth app with Honeycomb's MCP server using that redirect URI, then enter the app's Client ID and Client Secret on the connection. The name you give the connection is the connection_name your code passes, and the string must match the dashboard exactly. This is the most common integration error.
On the Honeycomb side, a Team Owner must enable Honeycomb Intelligence for each customer team, or every tool call fails. Copy SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, and SCALEKIT_CLIENT_SECRET from Developers > API Credentials into .env.
get_or_create_connected_account returns the user's connected account. If it is not ACTIVE, get_authorization_link returns the Honeycomb sign-in link the user opens once. Grant write access during consent only for users whose agent role needs to create boards, triggers, or markers. Then honeycombmcp_get_workspace_context confirms which team and environments this user's grant reaches.
This is not a catalog load. The agent asks for the tools this user's connected account is authorized to call, then narrows them to the eight an incident investigator needs. honeycombmcp_update_trigger, honeycombmcp_update_board, and honeycombmcp_create_recipient never reach the model, so it cannot change who gets paged while it explains a latency spike.
The loop runs until the model stops requesting tools. Every call executes with this engineer's Honeycomb grant and sees only the environments their role can see.
For pipelines, skip the model. execute_tool runs one tool with a fixed input and returns data plus an execution_id you can log. This post-deploy job marks the release on every dataset in the environment, then runs a fixed error-rate query by service for the last 30 minutes so a gate in your pipeline can compare it with the previous window. The connected account belongs to the engineer who triggered the deploy, so the marker and the query are attributed to them.
The run_query response is Markdown with a results table, a canonical query spec, and a metadata block containing query_run_pk and a query_url you can post to the release channel. When formulas are present, the table shows only breakdowns and formulas, which is why the spec adds the volume passthrough.
Scalekit does not ship a prebuilt connector for the Honeycomb REST API. Its custom connectors support API_KEY auth, which fits a Configuration key in X-Honeycomb-Team, but that key belongs to an environment, not to a user. For a team on Enterprise, the Query Data flow your pipeline runs looks like this:
The key needs the Manage Queries and Columns and Run Queries permissions, and Run Queries requires the Enterprise plan. Create one key per environment per customer, describe where it is used in the key's description, and rotate it on a schedule you own.
An incident agent rarely stops at one system. It investigates in Honeycomb, then posts what it found where the on-call team works. Load all 31 honeycombmcp tools and the model holds honeycombmcp_update_trigger, honeycombmcp_create_recipient, and the Canvas agent while answering a latency question. At roughly 200 tokens each, 31 tools is about 6,200 tokens before the agent does any work. The fix is not better prompting. It is surface reduction. A Scalekit virtual MCP server declares exactly which tools an agent role can see across connections, and session tokens keep each run bound to one user's connected accounts. Docs: set up a virtual MCP server.
One server definition serves every engineer at every customer. Before each run, check that the user's accounts are active and mint a short-lived session token scoped to them. Any MCP client that speaks Streamable HTTP can connect; this example uses langchain-mcp-adapters (pip install langchain-mcp-adapters) and passes the token as a Bearer header.
The agent sees six tools instead of 31 plus everything Slack exposes. The endpoint is static; the identity is per-user. Honeycomb's X-MCP-Toolset header narrows tools too, but only to the coarse query and canvas groups, and it applies to every user of a client; the virtual server picks individual tools per agent role.
Every execute_tool call returns an execution_id, and every execution is attributed to a connected account, which maps to one of your users and one customer. When a customer asks which agent run created the trigger that paged them at 03:00, or who put a deploy marker on the wrong dataset, the answer is a lookup, not an investigation. Honeycomb's own X-Honeycomb-Webhook-Delivery-ID and the query_url in every run_query result give you the Honeycomb side of the same record.
The API path is weaker by construction. A Configuration key belongs to an environment, so every query and every trigger your pipeline creates is recorded against that key, not against a person. If one key drives every engineer's requests, your side has to reconstruct which agent run, which prompt, and which user led there. Shared credentials are a single-user solution. They do not survive a second user.
Recommended reading: audit trails for agent auth
If your agent is an engineer's investigation partner in Claude Code, Cursor, or ChatGPT, running queries, BubbleUp, and traces while a human reads along, use Honeycomb's hosted MCP server: it is GA, included on every account with Honeycomb Intelligence enabled, and it does things the REST API can't. If you are building that agent into your own product for many customer teams, Scalekit's honeycombmcp connector gives each engineer a per-user OAuth grant without your code ever holding the token. If your agent marks deploys, gates releases on Query Data results, sends events, or provisions environments, keys, SLOs, and triggers per customer, build against the Honeycomb API. Either way, you hold a Honeycomb credential per user or per environment that can read production telemetry, and that's what needs production-grade infrastructure.
Yes. Honeycomb hosts a remote MCP server for US and EU teams, generally available since September 2025 and included on all accounts at no extra charge. The team must enable Honeycomb Intelligence first. Its tools reference lists 34 tools across querying, BubbleUp, traces, boards, triggers, SLOs, recipients and Canvas.
Only on Enterprise. Running a query through the REST API uses the Query Data API, which needs the Run Queries permission, is limited to 10 query results per minute and the last 7 days, and stops at 10 seconds of run time. On MCP, queries, BubbleUp and traces work on every plan with Honeycomb Intelligence.
Honeycomb recommends OAuth, where the user signs in and grants a read scope and an optional write scope for the nine write tools. The grant carries the user's role and can span several teams. Unattended agents can instead use a team-scoped Management key with the MCP and Environments scopes, created only by Team Owners.
Ingest keys and Configuration keys belong to one environment and are sent in a request header. Management keys belong to the team and manage environments and keys. The REST API has no OAuth, keys have no automatic expiry, and every call made with a key acts as that environment, not as a person.
Use the API for deploy pipelines that write markers and gate releases, for sending events, for provisioning environments, keys, SLOs, burn alerts and triggers per customer, and for configuration as code with Terraform. Use MCP when an engineer investigates latency or errors with a person reading along.
Scalekit's Honeycomb connector proxies Honeycomb's own MCP server with 31 tools. It runs the OAuth flow for each engineer, stores and refreshes their tokens in a vault, and executes every call with that engineer's grant. A virtual MCP server narrows the tools per agent role and binds each run to one user.
Browse the Scalekit Honeycomb MCP connector and the Honeycomb MCP connector docs with the full tool list. See Scalekit pricing, or talk to us.
