Observabilidad

Un servidor MCP tiene un problema peculiar de observabilidad: stdio pertenece al protocolo. Una línea de registro en el lugar equivocado corrompe el transporte. MCP Fusion mantiene los diagnósticos en canales separados, para que puedas inspeccionar un conector activo sin cambiar lo que recibe el agente.

Tres sinks, tres trabajos

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

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

Los tres permanecen inactivos hasta configurarse. Cuando falta un sink no se añade ningún wrapper, temporizador ni asignación al camino de la solicitud.

Eventos de DebugObserver

El observer recibe el pipeline a medida que ocurre: llegada de la solicitud, resolución de la herramienta, validación, middleware, handler, Presenter, respuesta y fallo. El middleware de seguridad añade eventos como security.firewall, security.rateLimit y security.audit; el sandbox emite sandbox.exec; los cambios de FSM emiten fsm.transition. El payload lleva la identidad de herramienta y acción, duración, estado del resultado y los metadatos seguros relevantes, nunca un secreto sin proteger.

El inspector usa el mismo stream mediante un Shadow Socket fuera de banda. Nunca escribe en stdout, así que un cliente stdio sigue siendo limpio para el protocolo mientras el terminal muestra llamadas, latencia, errores, herramientas activas y salida del Presenter.

mcpfusion inspect

Trazar la solicitud

Un tracer representa las mismas etapas como spans: route, parse, validate, middleware, execute, Present y serialize. Los atributos identifican la herramienta y la acción, si era destructiva o de solo lectura y la clase de error semántico. El framework separa un error del agente de un fallo upstream y de un fallo del lado de Vinkius, lo que hace accionable un panel de fiabilidad en vez de dejar un único contador rojo.

Conecta el tracer a tu exportador de OpenTelemetry en el límite. MCP Fusion es dueño del vocabulario de spans; tu exportador decide adónde van.

Telemetría y coste

El colector de telemetría registra los metadatos que necesita el sistema de gobernanza: rutas de redacción, decisiones del firewall, decisiones de rate limit, estado de auditoría, perfil de tokens, resultado del sandbox y transiciones de estado. Token Economics añade inflación estimada de entrada y salida, proporción de overhead y clasificación de riesgo. Son estimaciones basadas en texto con forma JSON, no afirmaciones de facturación del proveedor; el objetivo es comparar un cambio con el contrato anterior.

Seguridad de la observabilidad

Los eventos de auditoría aplican SHA-256 a los argumentos cuando se habilita hashArgs. El framework emite eventos a tu sink; no afirma que el sink OSS sea una cadena Ed25519 resistente a manipulaciones. En Vinkius Cloud, el conector alojado añade la pista de auditoría firmada y la retención de la consola. Ese límite importa en una revisión de cumplimiento.

Nunca registres ctx, credenciales, encabezados de autorización sin procesar ni todos los argumentos de la herramienta. Observa la clase de identidad, el hash del tenant, el nombre de la herramienta, la duración, el estado y un digest. Los eventos integrados siguen ese principio, pero un sink personalizado aún puede filtrar lo que pongas en él.

Configuración de producción

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,
});

Conecta al iniciar, no dentro de un handler. El registry propaga los sinks a builders existentes y a los registrados después. Cuando tracing y debug están activos a la vez, el framework da prioridad al tracing en el camino de diagnóstico compartido.

Próximos pasos

• Performance: qué se precompila y qué cuesta una solicitud
• Introspection: metadatos sin una llamada del cliente
• Contracts: convertir observabilidad en una barrera de release