Multi-Agent Monitoring LangFuse MCP Server

Un servidor del Protocolo de Contexto de Modelo (MCP) para la monitorización y observabilidad integral de sistemas multiagente utilizando Langfuse.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de monitoreo y observabilidad

Un servidor de Protocolo de Contexto de Modelo (MCP) para monitoreo y observabilidad integral de sistemas que utilizan Langfuse.

🎯 Qué hace esto

Este servidor MCP te permite:

  • Monitorear todos tus agentes en tiempo real
  • Rastrear métricas de rendimiento (latencia, costo, uso de tokens)
  • Depurar ejecuciones fallidas con trazas detalladas
  • Analizar el rendimiento de los agentes en períodos de tiempo
  • Comparar diferentes versiones de agentes mediante filtros de metadatos
  • Gestionar costos y configurar alertas de presupuesto
  • Visualizar flujos de trabajo de agentes

Inicio rápido

1. Requisitos previos

  • Python 3.11 o superior
  • Una cuenta de Langfuse (regístrate aquí)
  • Agentes instrumentados con Langfuse

2. Instalación

# Install via pip
pip install -r requirements.txt

# Or install from source
git clone https://github.com/yourusername/langfuse-mcp-python.git
cd langfuse-mcp-python
pip install -e .

3. Configuración

Crea un archivo .env con tus credenciales de Langfuse:

cp .env.example .env
# Edit .env and add your credentials

Tu .env debería verse así:

LANGFUSE_PUBLIC_KEY=pk-lf-xxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxx
LANGFUSE_HOST=https://cloud.langfuse.com

4. Ejecutar como HTTP Streamable (URL)

Si deseas una URL HTTP Streamable que funcione con todas las herramientas, ejecuta el servidor con el transporte HTTP Streamable:

python -m langfuse_mcp_python --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

python -m langfuse_mcp_python --transport sse --host 127.0.0.1 --port 8000

Luego puedes conectar cualquier cliente MCP compatible con HTTP Streamable a:

http://127.0.0.1:8000/mcp

Si estás usando Claude Desktop o Cursor, mantén el transporte stdio predeterminado en sus configuraciones.

4b. Configurar el cliente MCP

Para Claude Desktop

Agrega a claude_desktop_config.json:

{
  "mcpServers": {
    "langfuse-monitor": {
      "command": "uvx",
      "args": ["--python", "3.11", "langfuse-mcp-python"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxxxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxxxx",
        "LANGFUSE_HOST": "https://cloud.langfuse.com"
      }
    }
  }
}

Para Cursor

Agrega a .cursor/mcp.json:

{
  "mcpServers": {
    "langfuse-monitor": {
      "command": "python",
      "args": ["-m", "langfuse_mcp_python"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxxxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxxxx"
      }
    }
  }
}

5. Instrumenta tus agentes

Asegúrate de que tus agentes envíen trazas a Langfuse:

from langfuse.langchain import CallbackHandler
from langgraph.graph import StateGraph

# Create Langfuse callback handler
langfuse_handler = CallbackHandler(
    public_key="pk-lf-xxxxx",
    secret_key="sk-lf-xxxxx",
    host="https://cloud.langfuse.com"
)

# Create your agent
workflow = StateGraph(AgentState)
workflow.add_node("planner", planner_node)
workflow.add_node("executor", executor_node)
app = workflow.compile()

# Run with Langfuse monitoring
result = app.invoke(
    {"input": "user query"},
    config={
        "callbacks": [langfuse_handler],
        "metadata": {
            "agent_name": "my_planner_agent",
            "version": "v1.0"
        }
    }
)

Estructura del proyecto

  • src/langfuse_mcp_python/server.py Punto de entrada CLI y transporte stdio
  • src/langfuse_mcp_python/http_server.py Transporte HTTP Streamable y SSE
  • src/langfuse_mcp_python/utils/tool_registry.py Configuración y registro de herramientas
  • src/langfuse_mcp_python/tools/ Implementaciones y especificaciones de herramientas
  • src/langfuse_mcp_python/integrations/langfuse_client.py Cliente de API de Langfuse
  • src/langfuse_mcp_python/core/base_tool.py Caché y métricas compartidas

Herramientas disponibles

Monitoreo y análisis

  • watch_agents Monitorear agentes activos
  • get_trace Obtener una traza por ID
  • analyze_performance Agregar rendimiento a lo largo del tiempo
  • get_metrics Agregar métricas (latencia, costo, tokens)

Puntuaciones y evaluación

  • get_scores Obtener puntuaciones
  • submit_score Crear una puntuación
  • get_score_configs Listar configuraciones de puntuación

Prompts

  • get_prompts Listar prompts
  • create_prompt Crear un prompt
  • delete_prompt Eliminar un prompt

Sesiones

  • get_sessions Listar sesiones

Conjuntos de datos

  • get_datasets Listar conjuntos de datos
  • create_dataset Crear un conjunto de datos
  • create_dataset_item Agregar un elemento a un conjunto de datos

Modelos

  • get_models Listar modelos
  • create_model Crear un modelo
  • delete_model Eliminar un modelo

Comentarios

  • get_comments Listar comentarios
  • add_comment Agregar un comentario

Trazas

  • delete_trace Eliminar una traza

Colas de anotación

  • get_annotation_queues Listar colas de anotación
  • create_annotation_queue Crear una cola
  • get_queue_items Listar elementos de la cola
  • resolve_queue_item Resolver un elemento de la cola

Integraciones de almacenamiento de blobs

  • get_blob_storage_integrations Listar integraciones
  • upsert_blob_storage_integration Crear o actualizar una integración
  • get_blob_storage_integration_status Obtener el estado de la integración
  • delete_blob_storage_integration Eliminar una integración

Conexiones LLM

  • get_llm_connections Listar conexiones
  • upsert_llm_connection Crear o actualizar una conexión

Proyectos

  • get_projects Listar proyectos
  • create_project Crear un proyecto
  • update_project Actualizar un proyecto
  • delete_project Eliminar un proyecto

Ejemplo: watch_agents

Monitorea todos los agentes activos en tiempo real.

Ejemplo:

Show me all active agents from the last hour

Respuesta:

Active Agent Monitoring (last_1h)

Total Traces Found: 15
Showing: Top 10 traces

1. research_agent (Trace: trace-abc12...)
   - Status: completed
   - Session: session-xyz
   - Started: 2026-03-19T10:25:00Z
   - Latency: 1250ms
   - Tokens: 3420
   - Cost: $0.0234

Uso avanzado

Filtrado de agentes

Watch only my research_agent and planner_agent from the last 24 hours

Análisis de rendimiento

Analyze performance of my planner_agent over the last 24 hours

Monitoreo de costos

Show cost breakdown by agent for the last week

Depuración profunda

Show trace details for trace-abc123

Arquitectura

MCP Client (Claude, Cursor, etc.)
  -> Langfuse MCP Server (stdio/HTTP)
  -> Langfuse API
  -> Langfuse Platform
  -> Your Langfuse Agents

Mejores prácticas de seguridad

  1. Nunca confirmes credenciales - Usa variables de entorno
  2. Rota las claves de API regularmente
  3. Usa claves de solo lectura cuando sea posible
  4. Habilita la limitación de velocidad en producción
  5. Enmascara datos sensibles en las trazas

Ejemplo de flujo de trabajo de monitoreo

Verificación diaria de salud de agentes

  1. Verifica agentes activos: watch_agents
  2. Revisa el rendimiento: analyze_performance
  3. Verifica costos: get_metrics
  4. Investiga fallos: get_trace

Ciclo de optimización de agentes

  1. Establece una línea base: analyze_performance para los metadatos de la versión actual
  2. Implementa una nueva versión con metadatos diferentes
  3. Compara versiones ejecutando analyze_performance con filtros de versión
  4. Toma decisiones de implementación basadas en datos

Control de costos

  1. Rastrea costos: get_metrics agrupados por agente
  2. Identifica agentes costosos
  3. Optimiza operaciones de alto costo
  4. Rastrea ahorros a lo largo del tiempo

Solución de problemas

El servidor MCP no se conecta

  1. Verifica que las variables de entorno estén configuradas correctamente
  2. Verifica que las claves de API de Langfuse sean válidas
  3. Asegúrate de que Python 3.11+ esté instalado
  4. Revisa los registros: tail -f ~/.mcp/logs/langfuse-monitor.log

No se encontraron trazas

  1. Verifica que los agentes estén instrumentados con Langfuse
  2. Verifica que langfuse_handler se pase a las invocaciones de agentes
  3. Asegúrate de que los metadatos incluyan agent_name
  4. Verifica que la ventana de tiempo sea apropiada

Alta latencia

  1. Reduce el número de trazas obtenidas (usa filtros)
  2. Habilita el almacenamiento en caché: CACHE_ENABLED=true
  3. Usa profundidad "mínima" para los detalles de las trazas
  4. Considera el procesamiento por lotes para conjuntos de datos grandes

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Agrega pruebas para la nueva funcionalidad
  4. Envía una solicitud de extracción (pull request)

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles

Agradecimientos

Hoja de ruta

  • Herramientas de monitoreo principales
  • Análisis de rendimiento
  • Seguimiento de costos
  • Utilidades de depuración
  • Actualizaciones de transmisión en tiempo real
  • Sistema de alertas personalizado
  • Análisis predictivo
  • Soporte para pruebas A/B
  • Soporte para múltiples proyectos
  • Exportación a almacenes de datos

Versión: 1.0.0
Última actualización: 23 de marzo de 2026
Estado: Listo para producción