Honeycomb MCP

Interaja com dados de observabilidade do Honeycomb, incluindo conjuntos de dados, SLOs e triggers.

Documentação

Honeycomb MCP

⚠️ DESCONTINUADO: Este servidor MCP auto-hospedado está descontinuado. 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 datasets do Honeycomb em vários ambientes.

Requisitos

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

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 por 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 datasets 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 datasets 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 datasets 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 dataset
Informações da coluna (nome, tipo, descrição)
Detalhes do esquema

Ferramentas

list_datasets: Listar todos os datasets em um ambiente
```
{ "environment": "production" }
```

get_columns: Obter informações de colunas de um dataset

{
  "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 dataset executando consultas estatísticas e retornando métricas calculadas.

list_slos: Listar todos os SLOs de um dataset

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

get_slo: Obter informações detalhadas de SLO

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

list_triggers: Listar todos os triggers de um dataset

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

get_trigger: Obter informações detalhadas de 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 de instrumentação OpenTelemetry
```
{
  "language": "python",
  "filepath": "app/services/payment_processor.py"
}
```

Exemplos de Consultas com Claude

Pergunte a Claude coisas como:

"Quais datasets estão disponíveis no ambiente de produção?"
"Mostre-me a latência P95 do serviço de API na última hora"
"Qual é a taxa de erro dividida por nome do serviço?"
"Há algum SLO próximo de violar seu orçamento?"
"Mostre-me todos os triggers ativos no ambiente de staging"
"Quais colunas estão disponíveis no dataset da API de produção?"

Respostas Otimizadas de Ferramentas

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

Listar datasets: 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 de SLO: Simplificadas para indicadores de status e métricas de desempenho principais
Informações de trigger: Focadas no status do trigger, condições e destinos de notificação

Essa otimização garante que as respostas sejam concisas, porém 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 de consulta abrangente:

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 cálculos
- 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

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 de 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`