Heimdall

¿Qué es Heimdall?

Heimdall es una plataforma de observabilidad de código abierto diseñada específicamente para servidores Model Context Protocol (MCP) y aplicaciones de IA/LLM. Proporciona a desarrolladores, equipos de plataforma e ingenieros de IA una visibilidad profunda sobre cómo se ejecutan las herramientas, los recursos y los prompts dentro de su infraestructura de IA.

Basado en los estándares de OpenTelemetry, Heimdall recopila y visualiza trazas, métricas y analíticas en tiempo real de tus herramientas basadas en MCP y servicios de IA. Está pensado para ser autohospedado, lo que te da control total sobre tus datos y te permite monitorizar en detalle la latencia, las tasas de error, los patrones de uso y el comportamiento de las herramientas.

Al integrar SDKs ligeros en tus servidores MCP en Python o JavaScript/TypeScript, Heimdall facilita el trazado de cada llamada de herramienta y solicitud de recurso con cambios mínimos en el código existente. Es ideal para equipos que construyen agentes de IA, tooling y backends impulsados por LLM y que quieren observabilidad a nivel de producción sin quedar atados a un proveedor.

Funciones principales

• Trazado en tiempo real para servidores MCP
  Rastrea en tiempo real cada llamada de herramienta, acceso a recursos y ejecución relacionada con prompts. Heimdall muestra trazas detalladas que indican cuándo se invocó una herramienta, cuánto tardó, qué parámetros se pasaron y si tuvo éxito o falló.

• Analítica y visualizaciones en panel de control
  Utiliza el panel de control frontend integrado para analizar latencia, tasas de error y patrones de uso en tus servicios de IA. Detecta rápidamente herramientas lentas, endpoints que fallan o picos de uso inusuales.

• Arquitectura nativa de OpenTelemetry
  Heimdall utiliza OTLP/HTTP como protocolo de ingesta y está totalmente alineado con los estándares de OpenTelemetry. Esto facilita la integración con tus stacks de observabilidad existentes o la ampliación de tu canalización de telemetría.

• Integración sencilla del SDK para Python y JavaScript/TypeScript
  Heimdall ofrece un SDK oficial de Python (hmdl) y un SDK de JavaScript/TypeScript (hmdl) con decoradores/envoltorios sencillos:

  • Python: decorador @trace_mcp_tool() para trazar herramientas MCP.
  • JS/TS: envoltorio traceMCPTool() para funciones de herramientas asíncronas.

• Captura automática de parámetros
  El SDK de Python inspecciona automáticamente las firmas de las funciones para capturar los parámetros como objetos con nombre (por ejemplo, { "query": "test", "limit": 5 }). El SDK de JS/TS te permite especificar paramNames para lograr lo mismo, haciendo que las trazas sean más legibles y útiles para depuración.

• Despliegue autohospedado
  Actualmente Heimdall solo admite despliegue autohospedado, lo que te da control completo sobre la infraestructura, la seguridad y la residencia de los datos. Ejecutas tanto el backend como el frontend en tus propios servidores o en tu entorno de desarrollo local.

• Modelo de organización y proyecto
  Heimdall utiliza una estructura Organización → Proyecto:

  • Las organizaciones agrupan proyectos y equipos relacionados.
  • Los proyectos representan aplicaciones o entornos individuales, cada uno con un ID de proyecto único para la recopilación de trazas.

• Configuración basada en variables de entorno
  Configura los SDK de Heimdall mediante variables de entorno (por ejemplo, HEIMDALL_ENDPOINT, HEIMDALL_ORG_ID, HEIMDALL_PROJECT_ID, HEIMDALL_SERVICE_NAME, HEIMDALL_ENVIRONMENT, HEIMDALL_ENABLED) para facilitar el despliegue en desarrollo, preproducción y producción.

• Hoja de ruta futura (funciones previstas)
  El repositorio describe varias capacidades futuras:

  • Seguimiento de usuarios: asociar trazas con identidades de usuario para analítica a nivel de usuario (actualmente todas las solicitudes son anónimas).
  • Evaluación de LLM: puntuación integrada de calidad de modelo y flujos de trabajo de evaluación humana.
  • Alojamiento en la nube gestionado: despliegue gestionado opcional en la nube para equipos que prefieren no autohospedar.

Cómo usar Heimdall

Usar Heimdall implica tres pasos principales: poner en marcha la plataforma, crear una organización y un proyecto e integrar los SDK en tus servidores MCP o aplicaciones de IA.

1. Preparar los requisitos previos

Asegúrate de tener las dependencias de runtime necesarias:

• Node.js 18+ (para el backend y el frontend de Heimdall)
• Python 3.9+ (si planeas usar el SDK de Python)

Clona el repositorio de Heimdall desde GitHub y navega hasta él.

2. Iniciar el backend

Desde la raíz del proyecto:

cd backend
npm install
npm run dev

Esto inicia el backend de Heimdall, que expone un endpoint OTLP/HTTP (por defecto: http://localhost:4318) para la ingesta de trazas.

3. Iniciar el frontend

En una terminal separada:

cd frontend
npm install
npm run dev

El frontend suele estar disponible en http://localhost:5173, proporcionando la interfaz web para organizaciones, proyectos y analítica.

4. Crear una cuenta, una organización y un proyecto

1. Abre http://localhost:5173 en el navegador.
2. Crea una cuenta usando tu correo electrónico y contraseña.
3. Crea una Organización para agrupar tus proyectos.
4. Crea un Proyecto dentro de la organización. Cada proyecto obtiene un ID de proyecto único que se utiliza para asociar las trazas entrantes.

Luego ve a la página de Settings de tu proyecto para localizar:

• Organization ID
• Project ID

Usarás estos valores en la configuración del SDK.

5. Integrar el SDK de Python

Instala el paquete de Python:

pip install hmdl

Ejemplo básico de integración:

from hmdl import HeimdallClient, trace_mcp_tool

# Inicializar el cliente
client = HeimdallClient(
    endpoint="http://localhost:4318",
    org_id="your-org-id",       # Desde Settings
    project_id="your-project-id", # Desde Settings
    service_name="my-mcp-server",
    environment="development"
)

@trace_mcp_tool()
def search_tool(query: str, limit: int = 10) -> dict:
    return {"results": [], "query": query, "limit": limit}

result = search_tool("test", limit=5)
client.flush()

El decorador crea automáticamente trazas para cada invocación de search_tool, capturando los argumentos y los metadatos de ejecución.

6. Integrar el SDK de JavaScript/TypeScript

Instala el paquete de JS/TS:

npm install hmdl

Ejemplo básico de integración (estilo TypeScript):

import { HeimdallClient, traceMCPTool } from 'hmdl';

const client = new HeimdallClient({
  endpoint: "http://localhost:4318",
  orgId: "your-org-id",       // Desde Settings
  projectId: "your-project-id", // Desde Settings
  serviceName: "my-mcp-server",
  environment: "development",
});

const searchTool = traceMCPTool(
  async (query: string, limit: number = 10) => ({
    results: [],
    query,
    limit,
  }),
  {
    name: "search-tool",
    paramNames: ["query", "limit"],
  }
);

await searchTool("test", 5);
await client.flush();

7. Configurar mediante variables de entorno (opcional)

Puedes configurar el cliente de Heimdall usando variables de entorno en lugar de valores codificados en el código:

export HEIMDALL_ENDPOINT="http://localhost:4318"
export HEIMDALL_ORG_ID="your-org-id"
export HEIMDALL_PROJECT_ID="your-project-id"
export HEIMDALL_SERVICE_NAME="my-mcp-server"
export HEIMDALL_ENVIRONMENT="development"
export HEIMDALL_ENABLED="true"

Luego inicializa el cliente sin argumentos:

# Python
from hmdl import HeimdallClient
client = HeimdallClient()

// JavaScript/TypeScript
import { HeimdallClient } from 'hmdl';
const client = new HeimdallClient();

Una vez integrado, tus herramientas MCP emitirán telemetría hacia el backend de Heimdall, y podrás analizar trazas y métricas en la interfaz web.

Casos de uso

1. Observabilidad para agentes de IA y toolchains

Los equipos que construyen agentes de IA complejos que dependen de herramientas MCP necesitan entender cómo se comporta cada herramienta en cargas de trabajo reales. Heimdall proporciona:

• Seguimiento de latencia y monitorización de errores por herramienta.
• Visibilidad sobre qué herramientas se usan con más frecuencia.
• Información sobre cómo se accede a prompts y recursos a través de esas herramientas.

Esto ayuda a los equipos a optimizar la toolchain, retirar herramientas infrautilizadas y depurar el comportamiento de los agentes con mayor eficacia.

2. Monitorización en producción de backends con LLM

Para organizaciones que ejecutan APIs respaldadas por LLM o microservicios de IA en producción, Heimdall actúa como una capa crítica de observabilidad:

• Monitorizar el throughput de solicitudes y los tiempos de respuesta.
• Localizar rutas lentas causadas por dependencias externas o herramientas específicas.
• Detectar picos de error o regresiones tras despliegues.

Con Heimdall integrado vía OpenTelemetry, puedes alinear la observabilidad de IA con tu stack de monitorización general.

3. Desarrollo y depuración de servidores MCP

Durante el desarrollo, Heimdall ayuda a los ingenieros a depurar nuevos servidores MCP o herramientas:

• Trazar cada llamada a una nueva herramienta durante las pruebas.
• Inspeccionar parámetros y datos devueltos para verificar la corrección.
• Ver rápidamente dónde se lanzan excepciones y bajo qué condiciones.

Esto acelera los ciclos de feedback y reduce el tiempo necesario para identificar problemas en flujos de trabajo con múltiples herramientas y pasos.

4. Equipos internos de plataforma e infraestructura de IA

Los equipos de plataforma que proporcionan infraestructura interna de IA a varios equipos de producto pueden usar Heimdall para ofrecer observabilidad estandarizada:

• Crear proyectos separados para cada aplicación o inquilino (tenant).
• Monitorizar patrones de uso y rendimiento a nivel de organización.
• Utilizar el seguimiento futuro a nivel de usuario (previsto) para entender el consumo por equipo o cliente.

Esto permite una mejor planificación de capacidad, modelos de chargeback/showback y mayor fiabilidad del servicio.

5. Entornos con alta privacidad o regulados

Dado que Heimdall es autohospedado y de código abierto, es especialmente adecuado para organizaciones que operan en entornos altamente regulados o sensibles desde el punto de vista de la seguridad:

• Mantén todas las trazas y metadatos dentro de tu propia infraestructura.
• Alinea los despliegues con los requisitos internos de seguridad y cumplimiento.
• Personaliza la plataforma o intégrala con tus herramientas existentes de monitorización y alertas.

Preguntas frecuentes (FAQ)

¿Heimdall es gratuito?

Sí. Heimdall se publica bajo la licencia MIT, lo que lo hace gratuito y de código abierto tanto para uso personal como comercial. Tú eres responsable de alojar y ejecutar la plataforma en tu propia infraestructura. La hoja de ruta también menciona una posible oferta en la nube gestionada en el futuro, pero el proyecto principal es y seguirá siendo de código abierto.

¿Qué tecnologías y estándares utiliza Heimdall?

Heimdall está construido sobre OpenTelemetry y usa el protocolo OTLP/HTTP (puerto por defecto 4318) para ingerir datos de telemetría. El backend y el frontend son servicios basados en Node.js, y los SDK de cliente oficiales están disponibles para Python y JavaScript/TypeScript.

¿Qué entornos e idiomas están soportados?

Actualmente Heimdall proporciona SDKs oficiales para:

• Python (mediante el paquete hmdl; requiere Python 3.9+)
• JavaScript/TypeScript (mediante el paquete hmdl de npm; se ejecuta con Node.js 18+)

Como Heimdall habla OpenTelemetry/OTLP, también puedes integrar otros lenguajes usando librerías estándar de OpenTelemetry, aunque la experiencia más fluida se consigue con los SDK oficiales orientados a MCP.

¿Tengo que autohospedar Heimdall?

Sí, por el momento Heimdall está concebido como una plataforma autohospedada. Ejecutas tú mismo tanto los servicios de backend como de frontend (por ejemplo, en máquinas locales, VMs, Kubernetes o tu proveedor de hosting preferido). La hoja de ruta menciona un servidor en la nube gestionado como futura mejora, pero no forma parte de la versión actual.

¿Cómo configuro varios entornos (desarrollo, preproducción, producción)?

Heimdall admite configuración sensible al entorno mediante parámetros del SDK y variables de entorno. Un patrón común es:

• Usar diferentes Proyectos (e incluso Organizaciones) para cada entorno.
• Establecer variables como HEIMDALL_ENDPOINT, HEIMDALL_ORG_ID, HEIMDALL_PROJECT_ID, HEIMDALL_SERVICE_NAME y HEIMDALL_ENVIRONMENT de forma independiente en cada entorno.

Esto mantiene las trazas lógicamente separadas y facilita la comparación del comportamiento entre desarrollo, preproducción y producción.

¿Puede Heimdall asociar trazas con usuarios finales específicos?

El seguimiento a nivel de usuario está listado como una función pendiente en la hoja de ruta. Actualmente todas las solicitudes se tratan como anónimas y las identidades de usuario no se asocian a las trazas por defecto. El proyecto planea añadir compatibilidad para el seguimiento de usuarios y ofrecer analítica a nivel de usuario en futuras versiones.