Skip to main content
Understand how Honeycomb MCP uses Model Context Protocol to let AI agents explore your observability data.

​
What is Model Context Protocol?

Model Context Protocol (MCP) is a standard that lets AI agents and large language models (LLMs) interact with external tools and services in a consistent, structured way. With MCP, you can enable AI agents to perform specific actions, like browsing the web, editing local files, or fetching GitHub issues and pull requests.

​
Why does it matter?

You may already use AI tools like Cursor, Claude Code, Codename Goose, or one of the many (many) AI assistants that have emerged in the developer ecosystem since 2024. These tools have empowered developers and operators by expanding what LLMs, such as Anthropic Claude, OpenAI GPT, and DeepSeek R1, can do. Instead of only answering questions and generating text snippets, LLMs can now perform tasks by using tools. MCP provides a standardized way to define and expose those tools, making it easier for AI agents to discover and use them reliably.

​
How MCP servers fit in

An MCP server is the implementation of the MCP standard. It exposes your tools in a structured, machine-readable format. Think of the server as the bridge between AI agents and the services or data sources they need to interact with.

​
Honeycomb MCP Server

Honeycomb MCP Server brings Honeycomb’s observability investigation approach to LLMs via AI agents. It lets AI agents query, explore, and iterate on telemetry data just like you do in our UI. In practice, we have seen that AI agents using Honeycomb MCP can do meaningful work. They can:
  • Investigate and diagnose latency or error spikes
  • Identify performance outliers and suggest optimization opportunities
  • Translate existing dashboards and alerts into Honeycomb’s query language
We are excited to see the new ways you will use this integration to enhance your workflows.

​
Key concepts

Get familiar with how the Honeycomb MCP server works. Understanding these concepts will help you configure the server effectively, write better prompts, and get more useful results from your agents.

​
Tools

MCP makes Honeycomb functionality available to AI agents by exposing it as discrete tools. Each tool performs a specific task, like running a query, fetching a trace, creating a Board, or starting a Canvas investigation. To explore the full list of tools your agent can call, visit the MCP Tools Reference.

​
Security model

Honeycomb MCP follows the same security standards as the rest of the Honeycomb platform. Most tools are read-only. Write tools require the mcp:write scope, which you grant explicitly during OAuth consent or when configuring an API key. Write tools include creating or updating Boards, Triggers, SLOs, notification recipients, and Canvas investigations. The MCP Tools Reference lists every write tool and the scope it requires. This design limits agent access by default and expands it only when you explicitly grant permission.

​
Best practices

Getting your agent connected is just the start. How you prompt it, what context you give it, and how you configure your data all affect the quality of what it returns.

​
Write effective prompts

Your agent is only as good as the context you give it. Without clear direction, it has to guess at what you mean, and in observability, a wrong guess wastes time you don’t have during an incident. Some ways to guide your agent effectively include:
  • Be specific: Vague prompts like “Why is the system slow?” leave too much room for guesswork. Instead, try something more focused: “Investigate a latency spike between 12:00 and 13:00 in the api-gateway service.” Include details like service names, attributes, or signal types.
  • Provide context up front: If you are working with a specific codebase, run the agent from that repo and let it know that it can look at the code for details. Mention relevant services, environments, or datasets in your prompt to narrow its focus.
  • Use files to manage context across steps: For multi-step tasks, like plotting series data or comparing results over time, ask the agent to store responses in files. It can read those files later as it continues to reason or assemble output.

​
Customize attribute descriptions

The better your agent understands your data, the more useful its analysis will be. Investing time in describing your attributes pays off every time your agent runs a query or writes instrumentation. MCP tools like find_columns, get_dataset_columns, and search_semconv use Honeycomb’s attribute registry to describe your data to your agent, so well-described attributes produce better results. You can also define a custom telemetry schema for your team that overlays the standard OpenTelemetry and Honeycomb attribute definitions with your own. This gives agents richer, team-specific context when exploring your telemetry.

​
Capture findings with Boards

Investigation results are only useful if your team can find them later. Rather than letting findings disappear when a chat session ends, use Boards to capture and share what your agent discovers. The MCP server can create new Boards with create_board and edit existing Boards with update_board. Agents can also add, remove, update, and reorder query, SLO, and text panels on existing Boards, so you can capture investigation results on a Board you already use. To learn more about managing Boards, visit Manage Boards.

​
Next steps

Continue your MCP journey with these focused resources:
  • Connecting AI Agents to Honeycomb MCP: Follow step-by-step instructions to connect common agents to Honeycomb MCP.
  • Example Use Cases: Explore real-world use cases and tips for working with Honeycomb via MCP.
  • Troubleshooting: Find solutions to common configuration issues and learn how to verify that your agent is connected and working correctly.