# Honeycomb MCP

> Honeycomb MCP gives your AI agent full control over your observability data. Connect to Honeycomb.io from any compatible client to manage datasets, run complex queries, inspect schemas, and automate timeline markers using natural conversation.

## Overview
- **Category:** brain-trust
- **Price:** Free
- **Tags:** telemetry, high-cardinality, incident-response, data-querying, real-time-insights

## Description

This connector lets you treat your telemetry data like a chat interface. Instead of building out complicated query languages or clicking through dozens of dashboards, you just talk to it. Your agent handles the heavy lifting, letting you run deep performance analysis on high-cardinality event sources right from your client. You can ask to list all available datasets and immediately check their metadata. Need to know what fields a dataset tracks? Just ask for its schema. If something breaks, instead of manually building a query, you tell the system what you need, execute it, and get granular results fast. Plus, you can automatically annotate your timelines—saying 'Deployment v2.4 started'—so everyone sees exactly when key events happened. It’s like having a dedicated SRE sitting next to you, ready to run any check on demand. This makes complex observability data accessible through the Vinkius catalog.

## Tools

### create_marker
Adds a permanent annotation, like a deployment or maintenance window, directly onto a dataset's timeline.

### create_query_specification
Generates a formal query definition for a specific dataset, which you can then run later.

### run_query
Executes the defined query specification and returns a unique result ID that tracks its progress.

### get_dataset_details
Pulls general metadata about any specific dataset you are interested in.

### get_team_details
Retrieves organizational information, including details about the connected Honeycomb team.

### get_query_result
Fetches and displays the final data results using a query result ID you previously received.

### list_honeycomb_boards
Lists all shared dashboards or boards that are visible to your team configuration.

### list_dataset_columns
Displays a list of every column (field) available within a specified dataset's structure.

### list_datasets
Provides a comprehensive list of all datasets, giving you the necessary slug for further actions like queries or markers.

### list_markers
Shows existing timeline annotations (markers) that have already been placed on a dataset.

### list_queries
Retrieves saved or defined query specifications for a single dataset, helping you reuse work.

### list_triggers
Lists any active alerts (triggers) that have been set up and are monitoring the health of a specific dataset.

## Prompt Examples

**Prompt:** 
```
List all datasets and find one related to 'payment-gateway'.
```

**Response:** 
```
I've retrieved your datasets. I found 'gateway-prod' (Slug: gateway-prod) and 'gateway-staging'. Which dataset's schema would you like to inspect?
```

**Prompt:** 
```
Create a marker on all datasets: 'Deploy v2.4.0 started'.
```

**Response:** 
```
Marker created! I've successfully added the annotation 'Deploy v2.4.0 started' to all datasets using the environment-wide slug. You should see this marker appear on your graphs in a few moments.
```

**Prompt:** 
```
Execute query ID 'q_99283' for the 'main-api' dataset.
```

**Response:** 
```
Query execution triggered! Your result ID is 'res_552'. I'll wait a few moments for the data to process. Should I retrieve the final results for you now?
```

## Capabilities

### List available event sources
The agent retrieves metadata and access times for all datasets in your account.

### Run deep performance queries
You execute complex query specifications, receiving a result ID you can later use to retrieve the final data set.

### Annotate event timelines
The system creates permanent markers on your dataset timeline for events like deployments or outages.

### Inspect data structure
You list and view the specific columns (fields) contained within any given dataset.

### Review team configuration
The agent pulls information about shared boards and your Honeycomb team settings.

## Use Cases

### Investigating a sudden performance drop
The agent runs the following sequence: first, it uses `list_datasets` to confirm the correct event source. Then, it asks for schema insights on that dataset using `list_dataset_columns`. Finally, it executes a targeted query via `run_query` to pinpoint exactly when the drop started and what metrics were affected.

### Documenting an operational change
A platform lead needs to log that v3.1 was deployed across all services. They tell their agent, 'Create a marker on all datasets: Deploy v3.1 completed.' The agent uses `create_marker` and updates the shared timeline immediately for everyone.

### Reviewing team access and usage
A manager asks, 'What boards are available to us?' The agent calls `list_honeycomb_boards`, giving them a clear list of shared dashboards. They can also use `get_team_details` to confirm who has access.

### Verifying data completeness for audit
An engineer needs to know if the payment gateway dataset is complete. They first call `list_dataset_columns` to verify all required fields exist, and then use a query via `run_query` to check for records in the last 24 hours.

## Benefits

- Stop building complex query language DSLs for quick checks. You simply ask the agent to run a query, and it handles the structure needed.
- You get immediate visibility into your data's shape by running `list_dataset_columns`, so you know exactly which fields are available before writing any queries.
- During an incident, use the `create_marker` tool to instantly annotate the timeline for deployments or outages, making the root cause visible at a glance for every teammate.
- The agent handles the multi-step process of data analysis. You can ask it to find datasets using `list_datasets`, and then inspect their schema without switching tabs.
- You don't have to manually correlate event timelines anymore. The ability to create markers on all datasets means your entire team sees a consistent view of system history.

## How It Works

The bottom line is: you get to interact with complex observability data using simple conversation instead of writing code.

1. Subscribe to this MCP and provide your Honeycomb API key and preferred region (US or EU).
2. Tell your AI client what data you need—for example, 'Show me the schema for the payment-gateway dataset.'
3. The agent executes the necessary action, giving you results like query IDs or structured metadata that you can then review.

## Frequently Asked Questions

**How do I find my Honeycomb API Key?**
Log in to Honeycomb, go to **Team Settings**, and navigate to the **API Keys** section. You will be able to generate and copy your Team API Key from there. Ensure you also note your account's region.

**Which region should I select?**
If your browser URL starts with `ui.eu1.honeycomb.io`, select **EU**. Otherwise, select **US**. Using the correct region is required for the integration to connect to the right API cluster.

**Can I run a query and get the data back?**
Yes! Use the `run_query` tool with a valid query ID. It will return a result ID, which you can then pass to the `get_query_result` tool once the analysis is complete.

**Is the integration secure for telemetry data?**
Absolutely. The integration uses official Honeycomb Team API keys over HTTPS. Your credentials and queried data are encrypted and stored securely within the Vinkius Cloud infrastructure.