Honeycomb MCP

What is Honeycomb MCP about?

Honeycomb MCP is a self‑hosted server that implements the Model Context Protocol, allowing LLMs such as Claude to directly interact with Honeycomb datasets, alerts, dashboards, SLOs, and triggers. It bridges production telemetry with code‑level context for enterprise customers.

How to use Honeycomb MCP?

1. Install dependencies: pnpm install (Node.js 18+ required).
2. Build the server: pnpm run build; the compiled artifact appears in the build folder.
3. Configure environment variables in your MCP client config, supplying Honeycomb API keys and optional EU endpoint or caching settings.
4. Run the server (example):

   {
     "mcpServers": {
       "honeycomb": {
         "command": "node",
         "args": ["/full/path/to/honeycomb-mcp/build/index.mjs"],
         "env": { "HONEYCOMB_API_KEY": "<YOUR_API_KEY>" }
       }
     }
   }
   

5. Interact via compatible MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf, Goose, etc.) using the provided tools (list_datasets, run_query, list_slos, …).

Key features of Honeycomb MCP

• Query datasets with rich calculation support (COUNT, AVG, P95, HEATMAP, etc.)
• Multi‑environment support via environment URI scheme (honeycomb://prod/api-requests)
• SLO monitoring and trigger inspection (Enterprise only)
• Column discovery and statistical analysis tools
• TTL‑based caching for all non‑query API calls (configurable cache size and lifetimes)
• Simple STDIO communication—no network authentication required for the server process
• Compatibility with major MCP‑enabled LLM clients

Use cases of Honeycomb MCP

• Developer assistance: LLMs generate code snippets or troubleshooting steps by accessing live telemetry.
• Incident investigation: Quickly retrieve error rates, latency distributions, or trace links without leaving the LLM chat.
• Performance budgeting: Monitor SLO health and receive proactive alerts via LLM‑driven analysis.
• Cross‑environment comparison: Compare production vs. staging metrics using the same query interface.
• Automation scripts: Embed MCP calls in CI/CD pipelines to validate observability dashboards before release.

FAQ from the Honeycomb MCP

Q: Do I need a Honeycomb Enterprise license? A: Yes, the server requires an Enterprise account with full API permissions.

Q: Is the server authentication‑free? A: The server itself runs unauthenticated; access control is enforced by the API keys supplied via environment variables.

Q: Can I run the server in a container? A: Absolutely. Build the project, copy the build directory into an image, set the required env vars, and start the Node process.

Q: How does caching affect data freshness? A: Cached resources have configurable TTLs (default 5 minutes). Queries are never cached, ensuring real‑time analytics.

Q: What clients are officially supported? A: Claude Desktop, Claude Code, Cursor, Windsurf, Goose, and any MCP‑compatible client.

Honeycomb MCP

⚠️ DEPRECATED: This self-hosted MCP server is deprecated. Please migrate to the hosted Honeycomb Model Context Protocol (MCP) solution at Honeycomb MCP Documentation.

A Model Context Protocol server for interacting with Honeycomb observability data. This server enables LLMs like Claude to directly analyze and query your Honeycomb datasets across multiple environments.

Requirements

• Node.js 18+
• Honeycomb API key with full permissions:
  • Query access for analytics
  • Read access for SLOs and Triggers
  • Environment-level access for dataset operations

Honeycomb MCP is effectively a complete alternative interface to Honeycomb, and thus you need broad permissions for the API.

Honeycomb Enterprise Only

Currently, this is only available for Honeycomb Enterprise customers.

How it works

Today, this is a single server process that you must run on your own computer. It is not authenticated. All information uses STDIO between your client and the server.

Installation

pnpm install
pnpm run build

The build artifact goes into the /build folder.

Configuration

To use this MCP server, you need to provide Honeycomb API keys via environment variables in your MCP config.

{
    "mcpServers": {
      "honeycomb": {
        "command": "node",
        "args": [
          "/fully/qualified/path/to/honeycomb-mcp/build/index.mjs"
        ],
        "env": {
          "HONEYCOMB_API_KEY": "your_api_key"
        }
      }
    }
}

For multiple environments:

{
    "mcpServers": {
      "honeycomb": {
        "command": "node",
        "args": [
          "/fully/qualified/path/to/honeycomb-mcp/build/index.mjs"
        ],
        "env": {
          "HONEYCOMB_ENV_PROD_API_KEY": "your_prod_api_key",
          "HONEYCOMB_ENV_STAGING_API_KEY": "your_staging_api_key"
        }
      }
    }
}

Important: These environment variables must bet set in the env block of your MCP config.

EU Configuration

EU customers must also set a HONEYCOMB_API_ENDPOINT configuration, since the MCP defaults to the non-EU instance.

# Optional custom API endpoint (defaults to https://api.honeycomb.io)
HONEYCOMB_API_ENDPOINT=https://api.eu1.honeycomb.io/

Caching Configuration

The MCP server implements caching for all non-query Honeycomb API calls to improve performance and reduce API usage. Caching can be configured using these environment variables:

# Enable/disable caching (default: true)
HONEYCOMB_CACHE_ENABLED=true

# Default TTL in seconds (default: 300)
HONEYCOMB_CACHE_DEFAULT_TTL=300

# Resource-specific TTL values in seconds (defaults shown)
HONEYCOMB_CACHE_DATASET_TTL=900    # 15 minutes
HONEYCOMB_CACHE_COLUMN_TTL=900     # 15 minutes
HONEYCOMB_CACHE_BOARD_TTL=900      # 15 minutes
HONEYCOMB_CACHE_SLO_TTL=900        # 15 minutes
HONEYCOMB_CACHE_TRIGGER_TTL=900    # 15 minutes
HONEYCOMB_CACHE_MARKER_TTL=900     # 15 minutes
HONEYCOMB_CACHE_RECIPIENT_TTL=900  # 15 minutes
HONEYCOMB_CACHE_AUTH_TTL=3600      # 1 hour

# Maximum cache size (items per resource type)
HONEYCOMB_CACHE_MAX_SIZE=1000

Client compatibility

Honeycomb MCP has been tested with the following clients:

• Claude Desktop
• Claude Code
• Cursor
• Windsurf
• Goose

It will likely work with other clients.

Features

• Query Honeycomb datasets across multiple environments
• Run analytics queries with support for:
  • Multiple calculation types (COUNT, AVG, P95, etc.)
  • Breakdowns and filters
  • Time-based analysis
• Monitor SLOs and their status (Enterprise only)
• Analyze columns and data patterns
• View and analyze Triggers
• Access dataset metadata and schema information
• Optimized performance with TTL-based caching for all non-query API calls

Resources

Access Honeycomb datasets using URIs in the format: honeycomb://{environment}/{dataset}

For example:

• honeycomb://production/api-requests
• honeycomb://staging/backend-services

The resource response includes:

• Dataset name
• Column information (name, type, description)
• Schema details

Tools

• list_datasets: List all datasets in an environment

  { "environment": "production" }
  

• get_columns: Get column information for a dataset

  {
    "environment": "production",
    "dataset": "api-requests"
  }
  

• run_query: Run analytics queries with rich options

  {
    "environment": "production",
    "dataset": "api-requests",
    "calculations": [
      { "op": "COUNT" },
      { "op": "P95", "column": "duration_ms" }
    ],
    "breakdowns": ["service.name"],
    "time_range": 3600
  }
  

• analyze_columns: Analyzes specific columns in a dataset by running statistical queries and returning computed metrics.

• list_slos: List all SLOs for a dataset

  {
    "environment": "production",
    "dataset": "api-requests"
  }
  

• get_slo: Get detailed SLO information

  {
    "environment": "production",
    "dataset": "api-requests",
    "sloId": "abc123"
  }
  

• list_triggers: List all triggers for a dataset

  {
    "environment": "production",
    "dataset": "api-requests"
  }
  

• get_trigger: Get detailed trigger information

  {
    "environment": "production",
    "dataset": "api-requests",
    "triggerId": "xyz789"
  }
  

• get_trace_link: Generate a deep link to a specific trace in the Honeycomb UI

• get_instrumentation_help: Provides OpenTelemetry instrumentation guidance

  {
    "language": "python",
    "filepath": "app/services/payment_processor.py"
  }
  

Example Queries with Claude

Ask Claude things like:

• "What datasets are available in the production environment?"
• "Show me the P95 latency for the API service over the last hour"
• "What's the error rate broken down by service name?"
• "Are there any SLOs close to breaching their budget?"
• "Show me all active triggers in the staging environment"
• "What columns are available in the production API dataset?"

Optimized Tool Responses

All tool responses are optimized to reduce context window usage while maintaining essential information:

• List datasets: Returns only name, slug, and description
• Get columns: Returns streamlined column information focusing on name, type, and description
• Run query:
  • Includes actual results and necessary metadata
  • Adds automatically calculated summary statistics
  • Only includes series data for heatmap queries
  • Omits verbose metadata, links and execution details
• Analyze column:
  • Returns top values, counts, and key statistics
  • Automatically calculates numeric metrics when appropriate
• SLO information: Streamlined to key status indicators and performance metrics
• Trigger information: Focused on trigger status, conditions, and notification targets

This optimization ensures that responses are concise but complete, allowing LLMs to process more data within context limitations.

Query Specification for run_query

The run_query tool supports a comprehensive query specification:

• calculations: Array of operations to perform

  • Supported operations: COUNT, CONCURRENCY, COUNT_DISTINCT, HEATMAP, SUM, AVG, MAX, MIN, P001, P01, P05, P10, P25, P50, P75, P90, P95, P99, P999, RATE_AVG, RATE_SUM, RATE_MAX
  • Some operations like COUNT and CONCURRENCY don't require a column
  • Example: {"op": "HEATMAP", "column": "duration_ms"}

• filters: Array of filter conditions

  • Supported operators: =, !=, >, >=, <, <=, starts-with, does-not-start-with, exists, does-not-exist, contains, does-not-contain, in, not-in
  • Example: {"column": "error", "op": "=", "value": true}

• filter_combination: "AND" or "OR" (default is "AND")

• breakdowns: Array of columns to group results by

  • Example: ["service.name", "http.status_code"]

• orders: Array specifying how to sort results

  • Must reference columns from breakdowns or calculations
  • HEATMAP operation cannot be used in orders
  • Example: {"op": "COUNT", "order": "descending"}

• time_range: Relative time range in seconds (e.g., 3600 for last hour)

  • Can be combined with either start_time or end_time but not both

• start_time and end_time: UNIX timestamps for absolute time ranges

• having: Filter results based on calculation values

  • Example: {"calculate_op": "COUNT", "op": ">", "value": 100}

Example Queries

Here are some real-world example queries:

Find Slow API Calls

{
  "environment": "production",
  "dataset": "api-requests",
  "calculations": [
    {"column": "duration_ms", "op": "HEATMAP"},
    {"column": "duration_ms", "op": "MAX"}
  ],
  "filters": [
    {"column": "trace.parent_id", "op": "does-not-exist"}
  ],
  "breakdowns": ["http.target", "name"],
  "orders": [
    {"column": "duration_ms", "op": "MAX", "order": "descending"}
  ]
}

Distribution of DB Calls (Last Week)

{
  "environment": "production",
  "dataset": "api-requests",
  "calculations": [
    {"column": "duration_ms", "op": "HEATMAP"}
  ],
  "filters": [
    {"column": "db.statement", "op": "exists"}
  ],
  "breakdowns": ["db.statement"],
  "time_range": 604800
}

Exception Count by Exception and Caller

{
  "environment": "production",
  "dataset": "api-requests",
  "calculations": [
    {"op": "COUNT"}
  ],
  "filters": [
    {"column": "exception.message", "op": "exists"},
    {"column": "parent_name", "op": "exists"}
  ],
  "breakdowns": ["exception.message", "parent_name"],
  "orders": [
    {"op": "COUNT", "order": "descending"}
  ]
}

Development

pnpm install
pnpm run build

License

MIT