Honeycomb MCP

Un servidor de Protocolo de Contexto de Modelo para interactuar con los datos de observabilidad de Honeycomb. Este servidor permite a LLMs como Claude analizar y consultar directamente sus conjuntos de datos Honeycomb en múltiples entornos.

Requisitos

• Node.js 18+
• Clave API Honeycomb con permisos completos
  • Acceso de consulta para análisis
  • Acceso de lectura para SLO y Triggers
  • Acceso a nivel de entorno para operaciones con conjuntos de datos

Honeycomb MCP es efectivamente una interfaz alternativa completa a Honeycomb y, por lo tanto, necesita permisos amplios para la API.

Sólo para Honeycomb Enterprise

Actualmente, sólo está disponible para los clientes de Honeycomb Enterprise.

Cómo funciona

Actualmente, se trata de un único proceso de servidor que debes ejecutar en tu propio ordenador. No está autenticado. Toda la información utiliza STDIO entre su cliente y el servidor.

Instalación

pnpm install pnpm run build

El artefacto de compilación va a la carpeta /build.

Configuración

Para usar este servidor MCP, necesitas proporcionar claves de API Honeycomb a través de variables de entorno en tu configuración MCP.

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

Para múltiples entornos:

{ "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: Estas variables de entorno deben apostarse en el bloque env de su config MCP.

Configuración EU

Los clientes de la UE también deben establecer una configuración HONEYCOMB_API_ENDPOINT, ya que el MCP utiliza por defecto la instancia de fuera de la UE.

# Punto final de API personalizado opcional (por defecto https://api.honeycomb.io) HONEYCOMB_API_ENDPOINT=https://api.eu1.honeycomb.io/

Configuración del almacenamiento en caché

El servidor MCP implementa el almacenamiento en caché para todas las llamadas a la API Honeycomb que no sean consultas para mejorar el rendimiento y reducir el uso de la API. El almacenamiento en caché puede configurarse utilizando estas variables de entorno:

# HONEYCOMB_CACHE_ENABLED=true # TTL predeterminado en segundos (predeterminado: 300) HONEYCOMB_CACHE_DEFAULT_TTL=300 # Valores TTL específicos del recurso en segundos (por defecto: 300)tTL específicos de recursos en segundos (se muestran los valores por defecto) HONEYCOMB_CACHE_DATASET_TTL=900 # 15 minutos HONEYCOMB_CACHE_COLUMN_TTL=900 # 15 minutos HONEYCOMB_CACHE_BOARD_TTL=900 # 15 minutos HONEYCOMB_CACHE_SLO_TTL=900 # 15 minutos HONEYCOMB_CACHE_TRIGGER_TTL=900    # 15 minutos HONEYCOMB_CACHE_MARKER_TTL=900 # 15 minutos HONEYCOMB_CACHE_RECIPIENT_TTL=900 # 15 minutos HONEYCOMB_CACHE_AUTH_TTL=3600 # 1 hora Tamaño máximo de la caché (elementos por tipo de recurso) HONEYCOMB_CACHE_MAX_SIZE=1000

Compatibilidad con clientes

Honeycomb MCP ha sido probado con los siguientes clientes:

• Claude Desktop
• Claude Código
• Cursor
• Windsurf
• Ganso

Es probable que funcione con otros clientes.

Características

• Consulta de conjuntos de datos Honeycomb en múltiples entornos
• Ejecución de consultas analíticas con soporte para
  • Múltiples tipos de cálculo (COUNT, AVG, P95, etc.)
  • Desgloses y filtros
  • Análisis basados en el tiempo
• Supervisar los SLO y su estado (sólo Enterprise)
• Analizar columnas y patrones de datos
• Ver y analizar desencadenantes
• Acceso a metadatos de conjuntos de datos e información de esquemas
• Rendimiento optimizado con almacenamiento en caché basado en TTL para todas las llamadas a la API que no sean consultas

Recursos

Acceda a los conjuntos de datosHoneycomb mediante URI con el formato:honeycomb://{entorno}/{conjunto de datos}

Por ejemplo

• honeycomb://producción/api-solicitudes
• honeycomb:///staging/backend-services

La respuesta del recurso incluye

• Nombre del conjunto de datos
• Información de columna (nombre, tipo, descripción)
• Detalles del esquema

Herramientas

• list_datasets: Lista todos los conjuntos de datos de un entorno

  { "entorno": "production" }

• get_columns: Obtener información de las columnas de un conjunto de datos

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

• run_query: Ejecutar consultas de análisis con opciones enriquecidas

  { "entorno": "production", "dataset": "api-requests", "calculations": [ { "op": "COUNT" }, { "op": "P95", "column": "duration_ms" } ], "breakdowns": ["servicio.nombre"], "rango_tiempo": 3600 }

• analyze_columns: Analiza columnas específicas de un conjunto de datos ejecutando consultas estadísticas y devolviendo métricas calculadas.

• list_slos: Lista todos los SLO de un conjunto de datos

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

• get_slo: Obtener información detallada de SLO

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

• list_triggers: Lista todos los desencadenantes de un conjunto de datos

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

• get_trigger: Obtener información detallada sobre el desencadenador

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

• get_trace_link: Genera un enlace profundo a una traza específica en la interfaz de usuario Honeycomb

• get_instrumentation_help: Proporciona orientación sobre la instrumentación de OpenTelemetry

  { "language": "python", "filepath": "app/services/payment_processor.py" }

Ejemplo de consultas con Claude

Pregunte a Claude cosas como

• "¿Qué conjuntos de datos están disponibles en el entorno de producción?"
• "Muéstrame la latencia P95 para el servicio API durante la última hora"
• "¿Cuál es la tasa de errores desglosada por nombre de servicio?"
• "¿Hay algún SLO cerca de superar su presupuesto?"
• "Muéstrame todos los activadores activos en el entorno de ensayo"
• "¿Qué columnas están disponibles en el conjunto de datos de la API de producción?"

Respuestas optimizadas de las herramientas

Todas las respuestas de las herramientas se han optimizado para reducir el uso de la ventana de contexto, manteniendo al mismo tiempo la información esencial:

• Lista de conjuntos de datos: Sólo devuelve el nombre, el slug y la descripción
• Obtener columnas: Devuelve información simplificada sobre las columnas, centrándose en el nombre, el tipo y la descripción
• Ejecutar consulta
  • Incluye los resultados reales y los metadatos necesarios
  • Añade estadísticas de resumen calculadas automáticamente
  • Sólo incluye datos de series para las consultas de mapas térmicos
  • Omite metadatos verbose, enlaces y detalles de ejecución
• Columna de análisis
  • Devuelve valores máximos, recuentos y estadísticas clave
  • Calcula automáticamente métricas numéricas cuando procede
• Información SLO: Racionalizado a indicadores clave de estado y métricas de rendimiento
• Información deactivación: Centrada en el estado de activación, las condiciones y los objetivos de notificación

Esta optimización garantiza que las respuestas sean concisas pero completas, lo que permite a los LLM procesar más datos dentro de las limitaciones del contexto.

Especificación de consulta para run_query

La herramienta run_query admite una especificación de consulta completa:

• cálculos: Matriz de operaciones a realizar

  • Operaciones admitidas: 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
  • Algunas operaciones como CONTAR y CONCURRENCIA no requieren una columna
  • Ejemplo: {"op": "HEATMAP", "column": "duración_ms"}

• filtros: Matriz de condiciones de filtrado

  • Operadores admitidos: =, !=, >, >=, <, <=, empieza-con, no-empieza-con, existe, no-existe, contiene, no-contiene, en, no-en
  • Ejemplo: {"columna": "error", "op": "=", "valor": true}

• filtro_combinación: "AND" u "OR" (por defecto es "AND")

• desgloses: Matriz de columnas por las que agrupar los resultados

  • Ejemplo: ["servicio.nombre", "http.cod.estado"]

• órdenes: Matriz que especifica cómo ordenar los resultados

  • Debe hacer referencia a columnas de desgloses o cálculos
  • La operación HEATMAP no puede utilizarse en los pedidos
  • Ejemplo: {"op": "COUNT", "order": "descendente"}

• time_range: Rango de tiempo relativo en segundos (por ejemplo, 3600 para la última hora)

  • Puede combinarse con start_time o end_time, pero no con ambos

• start_time y end_time: Marcas de tiempo UNIX para rangos de tiempo absolutos

• tener: Filtrar los resultados en función de los valores de cálculo

  • Ejemplo: {"calcular_op": "CONTAR", "op": ">", "valor": 100}

Ejemplo de consulta

A continuación se muestran algunas consultas de ejemplo del mundo real:

Buscar llamadas lentas a la API

{ "entorno": "production", "dataset": "api-requests", "calculations": [ {"columna": "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"} ] }

Distribución de las llamadas a la base de datos (última semana)

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

Recuento de excepciones por excepción y llamante

{ "environment": "production", "dataset": "api-requests", "calculations": [ {"op": "COUNT"} ], "filters": [ {"columna": "exception.message", "op": "exists"}, {"column": "parent_name", "op": "exists"} ], "breakdowns": ["exception.message", "parent_name"], "orders": [ {"op": "COUNT", "order": "descending"} ] }

Desarrollo

pnpm install pnpm run build

Licencia

MIT