Multi-Agent Monitoring LangFuse MCP Server

Um servidor Model Context Protocol (MCP) para monitoramento e observabilidade abrangentes de sistemas multiagentes usando Langfuse.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP de Monitoramento e Observabilidade

Um servidor Model Context Protocol (MCP) para monitoramento e observabilidade abrangentes de sistemas usando Langfuse.

🎯 O Que Isso Faz

Este servidor MCP permite que você:

  • Monitore todos os seus agentes em tempo real
  • Acompanhe métricas de desempenho (latência, custo, uso de tokens)
  • Depure execuções com falha com traces detalhados
  • Analise o desempenho dos agentes ao longo de períodos de tempo
  • Compare diferentes versões de agentes por meio de filtros de metadados
  • Gerencie custos e defina alertas de orçamento
  • Visualize fluxos de trabalho dos agentes

Início Rápido

1. Pré-requisitos

  • Python 3.11 ou superior
  • Uma conta Langfuse (cadastre-se aqui)
  • Agentes instrumentados com Langfuse

2. Instalação

# 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. Configuração

Crie um arquivo .env com suas credenciais Langfuse:

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

Seu .env deve ser assim:

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

4. Executar como Streamable HTTP (URL)

Se você quiser uma URL Streamable HTTP que funcione em todas as ferramentas, execute o servidor com o transporte Streamable HTTP:

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

Você pode então conectar qualquer cliente MCP compatível com Streamable HTTP a:

http://127.0.0.1:8000/mcp

Se você estiver usando Claude Desktop ou Cursor, mantenha o transporte padrão stdio nas configurações deles.

4b. Configurar o Cliente MCP

Para Claude Desktop

Adicione 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

Adicione 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. Instrumente Seus Agentes

Certifique-se de que seus agentes enviem traces para 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"
        }
    }
)

Estrutura do Projeto

  • src/langfuse_mcp_python/server.py ponto de entrada CLI e transporte stdio
  • src/langfuse_mcp_python/http_server.py transporte Streamable HTTP e SSE
  • src/langfuse_mcp_python/utils/tool_registry.py configuração e registro de ferramentas
  • src/langfuse_mcp_python/tools/ implementações e especificações de ferramentas
  • src/langfuse_mcp_python/integrations/langfuse_client.py cliente da API Langfuse
  • src/langfuse_mcp_python/core/base_tool.py cache e métricas compartilhados

Ferramentas Disponíveis

Monitoramento e Análise

  • watch_agents Monitore agentes ativos
  • get_trace Busque um trace por ID
  • analyze_performance Agregue desempenho ao longo do tempo
  • get_metrics Agregue métricas (latência, custo, tokens)

Pontuações e Avaliação

  • get_scores Busque pontuações
  • submit_score Crie uma pontuação
  • get_score_configs Liste configurações de pontuação

Prompts

  • get_prompts Liste prompts
  • create_prompt Crie um prompt
  • delete_prompt Exclua um prompt

Sessões

  • get_sessions Liste sessões

Datasets

  • get_datasets Liste datasets
  • create_dataset Crie um dataset
  • create_dataset_item Adicione um item a um dataset

Modelos

  • get_models Liste modelos
  • create_model Crie um modelo
  • delete_model Exclua um modelo

Comentários

  • get_comments Liste comentários
  • add_comment Adicione um comentário

Traces

  • delete_trace Exclua um trace

Filas de Anotação

  • get_annotation_queues Liste filas de anotação
  • create_annotation_queue Crie uma fila
  • get_queue_items Liste itens da fila
  • resolve_queue_item Resolva um item da fila

Integrações de Armazenamento de Blobs

  • get_blob_storage_integrations Liste integrações
  • upsert_blob_storage_integration Crie ou atualize uma integração
  • get_blob_storage_integration_status Busque o status da integração
  • delete_blob_storage_integration Exclua uma integração

Conexões LLM

  • get_llm_connections Liste conexões
  • upsert_llm_connection Crie ou atualize uma conexão

Projetos

  • get_projects Liste projetos
  • create_project Crie um projeto
  • update_project Atualize um projeto
  • delete_project Exclua um projeto

Exemplo: watch_agents

Monitore todos os agentes ativos em tempo real.

Exemplo:

Show me all active agents from the last hour

Resposta:

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 Avançado

Filtrando Agentes

Watch only my research_agent and planner_agent from the last 24 hours

Análise de Desempenho

Analyze performance of my planner_agent over the last 24 hours

Monitoramento de Custos

Show cost breakdown by agent for the last week

Depuração Avançada

Show trace details for trace-abc123

Arquitetura

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

Boas Práticas de Segurança

  1. Nunca faça commit de credenciais - Use variáveis de ambiente
  2. Rotacione chaves de API regularmente
  3. Use chaves somente leitura quando possível
  4. Ative a limitação de taxa em produção
  5. Mascare dados sensíveis nos traces

Exemplo de Fluxo de Monitoramento

Verificação Diária de Saúde dos Agentes

  1. Verifique agentes ativos: watch_agents
  2. Revise o desempenho: analyze_performance
  3. Verifique custos: get_metrics
  4. Investigue falhas: get_trace

Ciclo de Otimização de Agentes

  1. Estabeleça uma linha de base: analyze_performance para os metadados da versão atual
  2. Implante uma nova versão com metadados diferentes
  3. Compare versões executando analyze_performance com filtros de versão
  4. Tome decisões de implantação baseadas em dados

Controle de Custos

  1. Acompanhe custos: get_metrics agrupados por agente
  2. Identifique agentes caros
  3. Otimize operações de alto custo
  4. Acompanhe as economias ao longo do tempo

Solução de Problemas

Servidor MCP Não Está Conectando

  1. Verifique se as variáveis de ambiente estão definidas corretamente
  2. Verifique se as chaves de API Langfuse são válidas
  3. Certifique-se de que o Python 3.11+ esteja instalado
  4. Verifique os logs: tail -f ~/.mcp/logs/langfuse-monitor.log

Nenhum Trace Encontrado

  1. Verifique se os agentes estão instrumentados com Langfuse
  2. Verifique se langfuse_handler é passado para as invocações dos agentes
  3. Certifique-se de que os metadados incluam agent_name
  4. Verifique se a janela de tempo é apropriada

Alta Latência

  1. Reduza o número de traces buscados (use filtros)
  2. Ative o cache: CACHE_ENABLED=true
  3. Use profundidade "mínima" para detalhes de traces
  4. Considere o processamento em lote para grandes datasets

Contribuindo

Contribuições são bem-vindas! Por favor:

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Adicione testes para novas funcionalidades
  4. Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes

Agradecimentos

Roadmap

  • Ferramentas principais de monitoramento
  • Análise de desempenho
  • Acompanhamento de custos
  • Utilitários de depuração
  • Atualizações de streaming em tempo real
  • Sistema de alertas personalizado
  • Análise preditiva
  • Suporte a testes A/B
  • Suporte a múltiplos projetos
  • Exportação para data warehouses

Versão: 1.0.0
Última Atualização: 23 de março de 2026
Status: Pronto para Produção