Honeycomb MCP

What is Honeycomb MCP about?

Honeycomb MCP provides a self‑hosted server that exposes Honeycomb datasets, alerts, dashboards, and other telemetry through a standardized protocol that LLMs can interact with. It lets AI assistants run analytics queries, list resources, and retrieve detailed metadata without needing direct API calls.

How to use Honeycomb MCP?

1. Install dependencies

   pnpm install
   pnpm run build
   

2. Run the server (or use the supplied serverConfig to start it via npx). The server reads configuration from environment variables.
3. Configure your MCP client (Claude, Cursor, etc.) to point to the server’s STDIO interface and include the appropriate environment variables for API keys and optional EU endpoint.
4. Invoke tools such as list_datasets, run_query, list_slos, or get_trigger from the LLM client to retrieve data.

Key features of Honeycomb MCP

• Query datasets with calculations (COUNT, AVG, P95, HEATMAP, etc.) and flexible filters.
• Support for multiple environments and EU endpoint configuration.
• TTL‑based caching for all non‑query API calls, drastically reducing request volume.
• Built‑in tools for listing datasets, columns, SLOs, triggers, and generating trace links.
• Optimized responses that minimize context window usage for LLMs.
• Compatible with major MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf, Goose).

Use cases of Honeycomb MCP

• Performance troubleshooting: Ask an LLM to surface latency percentiles or error rates across services.
• SLO monitoring: Retrieve current SLO status and identify those nearing breach.
• Alert management: List and examine active triggers to understand notification policies.
• Data exploration: Dynamically explore dataset schemas and column statistics via natural language.
• Cross‑environment analysis: Compare production vs. staging metrics without switching APIs.

FAQ from the Honeycomb MCP

Q: Do I need an Enterprise account? A: Yes, the server works only with Honeycomb Enterprise API keys that have full permissions.

Q: Is the server authenticated? A: The server itself is unauthenticated; authentication is handled via the API key supplied in environment variables.

Q: Can I run this in EU? A: Set HONEYCOMB_API_ENDPOINT to the EU endpoint (e.g., https://api.eu1.honeycomb.io/).

Q: How does caching work? A: Caching is enabled by default. TTLs and maximum cache size can be tuned with HONEYCOMB_CACHE_* environment variables.

Q: Is the project still maintained? A: The repository is deprecated; users are encouraged to migrate to the hosted Honeycomb MCP solution.

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