Observabilidade

Um servidor MCP tem um problema peculiar de observabilidade: o stdio pertence ao protocolo. Uma linha de log no lugar errado corrompe o transporte. O MCP Fusion mantém os diagnósticos em canais separados, para que você possa inspecionar um conector ativo sem mudar o que o agente recebe.

Três sinks, três funções

registry.enableDebug((event) => {
  console.error('[fusion]', event.type, event);
});

registry.enableTelemetry((event) => telemetry.write(event));
registry.enableTracing(tracer);

Os três ficam inertes até serem configurados. Nenhum wrapper, timer ou alocação é adicionado ao caminho da requisição quando não há sink.

Eventos do DebugObserver

O observer recebe o pipeline conforme ele acontece: chegada da requisição, resolução da ferramenta, validação, middleware, handler, Presenter, resposta e falha. O middleware de segurança acrescenta eventos como security.firewall, security.rateLimit e security.audit; o sandbox emite sandbox.exec; mudanças da FSM emitem fsm.transition. O payload carrega a identidade da ferramenta e da ação, duração, status do resultado e os metadados seguros relevantes, nunca um segredo bruto.

O inspetor usa o mesmo stream por meio de um Shadow Socket fora de banda. Ele nunca escreve em stdout, portanto um cliente stdio continua limpo para o protocolo enquanto o terminal mostra chamadas, latência, erros, ferramentas ativas e saída do Presenter.

mcpfusion inspect

Rastreando a requisição

Um tracer representa os mesmos estágios como spans: route, parse, validate, middleware, execute, Present e serialize. Os atributos identificam a ferramenta e a ação, se ela era destrutiva ou somente leitura e a classe de erro semântico. O framework separa um erro do agente de uma falha upstream e de uma falha do lado da Vinkius, tornando um painel de confiabilidade acionável em vez de um único contador vermelho.

Ligue o tracer ao seu exportador OpenTelemetry na fronteira. O MCP Fusion é dono do vocabulário dos spans; o exportador é dono do destino dos spans.

Telemetria e custo

O coletor de telemetria registra os metadados necessários ao sistema de governança: caminhos de redação, decisões do firewall, decisões de rate limit, status da auditoria, perfil de tokens, resultado do sandbox e transições de estado. Token Economics acrescenta inflação estimada de entrada e saída, proporção de overhead e classificação de risco. São estimativas baseadas em texto com formato JSON, não afirmações de faturamento do provedor; a finalidade é comparar uma mudança com o contrato anterior.

Segurança da observabilidade

Eventos de auditoria fazem hash dos argumentos com SHA-256 quando hashArgs está habilitado. O framework emite eventos para o seu sink; não afirma que o sink OSS seja uma cadeia Ed25519 à prova de adulteração. No Vinkius Cloud, o conector hospedado acrescenta a trilha de auditoria assinada e a retenção no console. Essa fronteira importa em uma revisão de conformidade.

Nunca registre ctx, credenciais, cabeçalhos de autorização brutos ou argumentos completos da ferramenta. Observe a classe de identidade, o hash do tenant, o nome da ferramenta, a duração, o status e um digest. Os eventos integrados seguem esse princípio, mas um sink customizado ainda pode vazar o que você colocar nele.

Configuração de produção

const observer = createDebugObserver({
  sink: (event) => process.stderr.write(JSON.stringify(event) + '\n'),
});

await registry.attachToServer(server, {
  debug: observer,
  telemetry: (event) => metrics.record(event),
  tracing: otelTracer,
});

Conecte na inicialização, não dentro de um handler. O registry propaga sinks para builders existentes e para builders registrados depois. Quando tracing e debug estão ativos ao mesmo tempo, o framework dá precedência ao tracing no caminho diagnóstico sobreposto.

Próximos passos

• Performance: o que é pré-compilado e o que custa uma requisição
• Introspection: metadados sem uma chamada do cliente
• Contracts: transformar observabilidade em um gate de release