Honeycomb MCP

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.

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

Requirements

Node.js 16+
Honeycomb API keys with appropriate permissions:
- Query access for analytics
- Read access for SLOs and Triggers
- Environment-level access for dataset operations

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Honeycomb MCP

Honeycomb Enterprise Only

How it works

Installation

Configuration

EU Configuration

Caching Configuration

Client compatibility

Features

Resources

Tools

Example Queries with Claude

Optimized Tool Responses

Query Specification for `run_query`

Example Queries

Find Slow API Calls

Distribution of DB Calls (Last Week)

Exception Count by Exception and Caller

Development

Requirements

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

Honeycomb MCP

Honeycomb Enterprise Only

How it works

Installation

Configuration

EU Configuration

Caching Configuration

Client compatibility

Features

Resources

Tools

Example Queries with Claude

Optimized Tool Responses

Query Specification for run_query

Example Queries

Find Slow API Calls

Distribution of DB Calls (Last Week)

Exception Count by Exception and Caller

Development

Requirements

License

Query Specification for `run_query`