observer-launch-mcp

Haz preguntas a Claude sobre tus datos de Observe -- errores recientes, fallos comunes, volumen de logs por pod -- sin escribir OPAL a mano. Este es un servidor MCP que le da a Claude acceso directo y en vivo a tu tenant de Observe.

Configuración (2 pasos)

1. Ejecuta el asistente de configuración. Te pide tus credenciales de Observe y alias de datasets, y luego se registra automáticamente con Claude Code:

npx @aryanbansal-launch/observer-launch-mcp init

Se te pedirá:

• ID de cliente de Observe -- un número, que se encuentra en tu URL de Observe.

• Clave API de Observe -- crea una en Manage account → My API tokens. (No es un token de ingest/datastream -- se ven similares pero no funcionan aquí.)

• Cluster -- p. ej. eu-1. Déjalo en blanco si estás en el tenant de EE. UU. por defecto.

• Alias de datasets (opcional) -- nombres amigables para datasets sobre los que preguntarás a menudo, p. ej. launch-management → 41249178. Encuentra el ID en la interfaz de Observe: abre un dataset, está en la URL. Puedes omitir esto y usar IDs de dataset sin procesar, o añadir alias más tarde.

2. Reinicia Claude Code (o inicia una nueva sesión) para que detecte el nuevo servidor. Confirma que funcionó:

Is the Observe connection working?

Eso es todo -- las demás herramientas de abajo ya están disponibles en el chat.

claude mcp add observe -s user \
  -e OBSERVE_CUSTOMER_ID=<your id> \
  -e OBSERVE_API_KEY=<your token> \
  -e OBSERVE_CLUSTER=eu-1 \
  -e OBSERVE_DATASETS='{"launch-management":"41249178"}' \
  -- node <path to installed server.js>

Ejecuta npx @aryanbansal-launch/observer-launch-mcp init una vez primero si solo quieres esa ruta absoluta -- imprime el comando exacto que ejecutaría, justo antes de ejecutarlo. Usa un comando directo node <path>, no npx <package> como entrada final -- Claude Code lanza los servidores registrados con un entorno mínimo (sin PATH), y el shebang de npx necesita PATH para encontrar node, así que npx como comando muestra silenciosamente "Fallo al conectar." El asistente ya evita esto por ti.

Related MCP server: Fathom AI MCP Server

Qué puedes preguntar

Una vez configurado, solo habla con Claude de forma natural:

• "¿Está funcionando la conexión con Observe?"

• "¿Qué alias de servicios/datasets tengo configurados?"

• "Muéstrame errores recientes de launch-management en la última hora"

• "¿Cuál es nuestro error más común en launch-nginx esta semana?"

• "¿Qué pods están registrando más en launch-management-bg ahora mismo?"

• "¿Cuánta salida stderr está produciendo launch-nginx en las últimas 6 horas?"

• "Cuenta las líneas de log por pod en launch-telemetry durante la última hora"

• "Trae las últimas 20 líneas de log sin procesar de launch-logs-bg-exporter"

Para cualquier cosa no cubierta por una forma de pregunta específica, solo describe lo que quieres -- Claude escribirá el pipeline de OPAL por ti usando la herramienta de consulta general.

Referencia de herramientas

get_error_summary y get_log_stats agregan en el lado del servidor, por lo que siguen siendo rápidos independientemente de la ventana de tiempo. get_service_errors y run_opal_query añadirán una advertencia si consultas una ventana de 6h+ sin agregar, ya que los volcados de filas sin procesar en una ventana amplia arriesgan el límite de 100k filas de Observe.

Formatos de log

Los datasets en un mismo tenant rara vez comparten un esquema de log, así que get_service_errors y get_error_summary detectan el formato por dataset (una vez por proceso) y construyen la consulta correspondiente:

Cada resultado indica qué formato se detectó. Para omitir la prueba, decláralo en tu configuración de dataset:

{ "launch-nginx": { "id": "41250854", "shape": "http" } }

Las entradas simples "alias": "id" siguen funcionando y se detectan automáticamente.

La cobertura se informa, no se oculta. En datasets de level, algunas líneas no tienen un campo level analizable (un stack trace, una cadena simple, salida no JSON) y un filtro de severidad no puede verlas. Cuando esa proporción supera el 1%, las herramientas lo indican:

Note: 529 of 2136 rows (24.8%) have no parseable "level" field and were not
scanned. Pass includeUnparsed=true to keyword-match those too.

includeUnparsed=true escanea esas líneas por palabras clave. Es opcional porque la coincidencia de palabras clave también marca líneas info que simplemente contienen la palabra "error".

Referencia de configuración

Los IDs de dataset son específicos del tenant y no se incluyen intencionalmente con este paquete. Sin ninguno configurado, las búsquedas de alias fallan y aún puedes pasar IDs de dataset numéricos sin procesar directamente a cualquier herramienta.

Solución de problemas

• La comprobación de salud falla → tu clave API probablemente sea un token de ingest/datastream, no uno de Manage account → My API tokens. Regenera.

• claude mcp list muestra "Fallo al conectar" en una entrada registrada manualmente → verifica que el comando sea node <path>, no npx <package> (ver la nota anterior).

• Una herramienta devuelve "Servicio/dataset desconocido" → ejecuta list_known_services para ver qué está configurado, o pasa un ID de dataset numérico sin procesar.

• get_service_errors/get_error_summary no devuelven nada útil → revisa la nota "Formato de log detectado" en el resultado. Si adivinó mal, fija el formato explícitamente con {"alias": {"id": "...", "shape": "http"}} (ver Formatos de log). Si dice text, tus logs no tienen campo de severidad y la coincidencia se basa en palabras clave.

• Errores que puedes ver en la interfaz de Observe faltan en los resultados → busca la nota de cobertura. Las líneas sin level analizable se omiten por defecto; pasa includeUnparsed=true.

Contribuciones

npm install
npm run build   # tsc, then chmod +x on the bin entry
npm publish      # only if you intend to ship a new version

Copia el patrón de get_error_summary/get_log_stats en src/run-server.ts para otras consultas OPAL recurrentes (p. ej. costo por servicio, percentiles de latencia) -- dale a la herramienta un nombre/descripción descriptiva para que Claude la elija sobre run_opal_query cuando sea apropiado.