Honeycomb MCP

Interaja com dados de observabilidade do Honeycomb usando o Model Context Protocol.

Servidor MCP hospedado

npx add-mcp 'https://mcp.honeycomb.io/mcp'

Instala no Claude Code, Codex, Cursor e outros

Documentação

Honeycomb MCP

⚠️ DEPRECADO: Este servidor MCP auto-hospedado está obsoleto. Por favor, migre para a solução hospedada Honeycomb Model Context Protocol (MCP) em Documentação do Honeycomb MCP.

Um servidor Model Context Protocol para interagir com dados de observabilidade do Honeycomb. Este servidor permite que LLMs como o Claude analisem e consultem diretamente seus conjuntos de dados do Honeycomb em vários ambientes.

Requisitos

Node.js 18+
Chave de API do Honeycomb com permissões completas:
- Acesso a consultas para análises
- Acesso de leitura para SLOs e Triggers
- Acesso em nível de ambiente para operações de conjuntos de dados

O Honeycomb MCP é efetivamente uma interface alternativa completa para o Honeycomb e, portanto, você precisa de permissões amplas para a API.

Somente Honeycomb Enterprise

Atualmente, isso está disponível apenas para clientes Honeycomb Enterprise.

Como funciona

Hoje, este é um processo de servidor único que você deve executar no seu próprio computador. Ele não é autenticado. Todas as informações usam STDIO entre seu cliente e o servidor.

Instalação

pnpm install
pnpm run build

O artefato de build vai para a pasta /build.

Configuração

Para usar este servidor MCP, você precisa fornecer chaves de API do Honeycomb por meio de variáveis de ambiente na sua configuração MCP.

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

Para vários ambientes:

{
    "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"
        }
      }
    }
}

Importante: Essas variáveis de ambiente devem ser definidas no bloco env da sua configuração MCP.

Configuração da UE

Clientes da UE também devem definir uma configuração HONEYCOMB_API_ENDPOINT, já que o MCP usa como padrão a instância fora da UE.

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

Configuração de Cache

O servidor MCP implementa cache para todas as chamadas de API do Honeycomb que não são de consulta, para melhorar o desempenho e reduzir o uso da API. O cache pode ser configurado usando estas variáveis de ambiente:

# 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

Compatibilidade com clientes

O Honeycomb MCP foi testado com os seguintes clientes:

Provavelmente funcionará com outros clientes.

Recursos

Consultar conjuntos de dados do Honeycomb em vários ambientes
Executar consultas de análise com suporte para:
- Múltiplos tipos de cálculo (COUNT, AVG, P95, etc.)
- Agrupamentos e filtros
- Análise baseada em tempo
Monitorar SLOs e seu status (somente Enterprise)
Analisar colunas e padrões de dados
Visualizar e analisar Triggers
Acessar metadados de conjuntos de dados e informações de esquema
Desempenho otimizado com cache baseado em TTL para todas as chamadas de API que não são de consulta

Recursos

Acesse conjuntos de dados do Honeycomb usando URIs no formato: honeycomb://{environment}/{dataset}

Por exemplo:

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

A resposta do recurso inclui:

Nome do conjunto de dados
Informações da coluna (nome, tipo, descrição)
Detalhes do esquema

Ferramentas

list_datasets: Listar todos os conjuntos de dados em um ambiente
```
{ "environment": "production" }
```
get_columns: Obter informações de colunas para um conjunto de dados
```
{
  "environment": "production",
  "dataset": "api-requests"
}
```

run_query: Executar consultas de análise com opções avançadas

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

analyze_columns: Analisa colunas específicas em um conjunto de dados executando consultas estatísticas e retornando métricas calculadas.

list_slos: Listar todos os SLOs para um conjunto de dados

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

get_slo: Obter informações detalhadas do SLO

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

list_triggers: Listar todos os triggers para um conjunto de dados
```
{
  "environment": "production",
  "dataset": "api-requests"
}
```

get_trigger: Obter informações detalhadas do trigger

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

get_trace_link: Gerar um link profundo para um trace específico na interface do Honeycomb
get_instrumentation_help: Fornece orientação sobre instrumentação OpenTelemetry
```
{
  "language": "python",
  "filepath": "app/services/payment_processor.py"
}
```

Exemplos de Consultas com Claude

Pergunte ao Claude coisas como:

"Quais conjuntos de dados estão disponíveis no ambiente de produção?"
"Mostre-me a latência P95 para o serviço de API na última hora"
"Qual é a taxa de erro dividida por nome do serviço?"
"Existem SLOs próximos de violar seu orçamento?"
"Mostre-me todos os triggers ativos no ambiente de staging"
"Quais colunas estão disponíveis no conjunto de dados da API de produção?"

Respostas Otimizadas das Ferramentas

Todas as respostas das ferramentas são otimizadas para reduzir o uso da janela de contexto, mantendo informações essenciais:

Listar conjuntos de dados: Retorna apenas nome, slug e descrição
Obter colunas: Retorna informações simplificadas de colunas, focando em nome, tipo e descrição
Executar consulta:
- Inclui resultados reais e metadados necessários
- Adiciona estatísticas resumidas calculadas automaticamente
- Inclui dados de série apenas para consultas de heatmap
- Omite metadados verbosos, links e detalhes de execução
Analisar coluna:
- Retorna valores principais, contagens e estatísticas-chave
- Calcula automaticamente métricas numéricas quando apropriado
Informações do SLO: Simplificadas para indicadores-chave de status e métricas de desempenho
Informações do trigger: Focadas no status do trigger, condições e destinos de notificação

Essa otimização garante que as respostas sejam concisas, mas completas, permitindo que LLMs processem mais dados dentro das limitações de contexto.

Especificação de Consulta para `run_query`

A ferramenta run_query suporta uma especificação abrangente de consulta:

calculations: Matriz de operações a serem executadas
- Operações suportadas: 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
- Algumas operações como COUNT e CONCURRENCY não exigem uma coluna
- Exemplo: {"op": "HEATMAP", "column": "duration_ms"}
filters: Matriz de condições de filtro
- Operadores suportados: =, !=, >, >=, <, <=, starts-with, does-not-start-with, exists, does-not-exist, contains, does-not-contain, in, not-in
- Exemplo: {"column": "error", "op": "=", "value": true}
filter_combination: "AND" ou "OR" (o padrão é "AND")
breakdowns: Matriz de colunas para agrupar resultados
- Exemplo: ["service.name", "http.status_code"]
orders: Matriz que especifica como ordenar os resultados
- Deve referenciar colunas de breakdowns ou calculations
- A operação HEATMAP não pode ser usada em orders
- Exemplo: {"op": "COUNT", "order": "descending"}
time_range: Intervalo de tempo relativo em segundos (ex.: 3600 para a última hora)
- Pode ser combinado com start_time ou end_time, mas não com ambos
start_time e end_time: Timestamps UNIX para intervalos de tempo absolutos
having: Filtrar resultados com base em valores de cálculo
- Exemplo: {"calculate_op": "COUNT", "op": ">", "value": 100}

Exemplos de Consultas

Aqui estão alguns exemplos de consultas do mundo real:

Encontrar Chamadas Lentas de API

{
  "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"}
  ]
}

Distribuição de Chamadas de Banco de Dados (Última Semana)

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

Contagem de Exceções por Exceção e Chamador

{
  "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"}
  ]
}

Desenvolvimento

pnpm install
pnpm run build

Licença

MIT

Honeycomb MCP

Servidor MCP hospedado

Documentação

Honeycomb MCP

Requisitos

Somente Honeycomb Enterprise

Como funciona

Instalação

Configuração

Configuração da UE

Configuração de Cache

Compatibilidade com clientes

Recursos

Recursos

Ferramentas

Exemplos de Consultas com Claude

Respostas Otimizadas das Ferramentas

Especificação de Consulta para run_query

Exemplos de Consultas

Encontrar Chamadas Lentas de API

Distribuição de Chamadas de Banco de Dados (Última Semana)

Contagem de Exceções por Exceção e Chamador

Desenvolvimento

Licença

Especificação de Consulta para `run_query`