MCP Observability — health cron, logs e alertas

Nota de 28/09/2026. O guia docs/MCP-ONBOARDING.md, citado no fim desta nota, mora no repositório interno e não abre para quem está fora do time. O que vale para clientes está na central de ajuda, em Ferramentas & MCP.

Fase 5 do sprint de MCP entregue. Objetivo: você descobrir problemas de MCP antes do usuário final descobrir.

Cron de health monitoring (a cada 10 minutos)

Todos os servidores MCP ativos são pingados automaticamente a cada 10 minutos. O cron:

• Conecta e lista as ferramentas (mesmo fluxo que um agente faria).
• Atualiza o status do servidor em MCP Servers (saudável, degradado ou indisponível).
• Fecha circuit breakers expirados para servidores que voltaram ao ar.

Quando um servidor fica offline por mais de 15 minutos, um email automático vai para o owner do workspace com:

• Qual servidor caiu e desde quando.
• Último erro reportado (código + mensagem técnica).
• Link direto para o painel para diagnosticar.

O email só é enviado uma vez por janela de outage — não faz spam. Quando o servidor recupera, o contador zera e a próxima queda volta a alertar.

Página de logs

Novo acesso em MCP Servers → Ver logs (/dashboard/mcp/logs):

• Timeline de todas as chamadas de ferramenta com status (OK, erro, timeout, rate limited, circuit open, aguardando aprovação, rejeitado).
• Filtros: janela (24h, 7d, 30d ou tudo), servidor, status, trace ID.
• Clique numa linha para abrir um modal com input, output, latency e trace_id completo.

O trace ID é o mesmo que vai no header X-Turn-Id das respostas do chat. Se um usuário reportar "essa conversa falhou", você pega o trace id da conversa e filtra direto nos logs.

Schema cache invalidation automática

Quando um servidor MCP adiciona ou remove tools, a ControlHub recebe a notificação tools/list_changed e atualiza o cache na hora. Antes, você tinha que esperar até 1 hora para o cache expirar e o agente descobrir a tool nova.

Para servidores que não emitem a notificação (legacy), o fallback de TTL de 1 hora + health cron de 10 minutos continua garantindo atualização regular.

Correções da camada MCP

• Timeout por chamada aumentado de 10 para 30 segundos — Context7 query-docs às vezes leva 15 a 20 segundos para queries amplas.
• Timeout do load por servidor em vez de global — se um servidor travar, os outros continuam funcionando (antes, um servidor lento descartava todo o tool set).
• Cap de 8KB por resultado de tool — retornos gigantes (documentações inteiras, grandes resultados de query) são truncados com marcador para o LLM saber que pode pedir algo mais específico.

Correções do chat

• Paginação do histórico — conversas longas agora carregam em páginas de 50 mensagens com infinite scroll no topo, sem perder a posição no meio.
• Timeouts do stream — removido retry em stream (anti-pattern), cleanup das conexões MCP agora roda mesmo em abort.
• Error boundary no chat — se algo explode no React do chat, aparece uma tela com ref ID para você reportar, em vez de página branca.
• Trace ID visível no header X-Turn-Id de toda resposta.

Docs atualizadas

Todo o subsistema de MCP tem agora um guia operacional dev-facing em docs/MCP-ONBOARDING.md cobrindo o fluxo end-to-end, segurança, endpoints, env vars e runbook para incidentes comuns.