Observability

An MCP server has a peculiar observability problem: stdio belongs to the protocol. A log line in the wrong place corrupts the transport. MCP Fusion keeps diagnostics on separate channels, so you can inspect a live connector without changing what the agent receives.

Three sinks, three jobs

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

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

All three are inert until configured. No wrapper, timer or allocation is added to the request path when a sink is absent.

DebugObserver events

The observer receives the pipeline as it happens: request arrival, tool resolution, validation, middleware, handler, Presenter, response and failure. Security middleware adds events such as security.firewall, security.rateLimit and security.audit; the sandbox emits sandbox.exec; FSM changes emit fsm.transition. The payload carries the tool/action identity, duration, result status and the relevant safe metadata, never a raw secret.

The inspector uses the same stream over an out-of-band Shadow Socket. It never writes into stdout, so a stdio client remains protocol-clean while the terminal shows calls, latency, errors, active tools and Presenter output.

mcpfusion inspect

Tracing the request

A tracer represents the same stages as spans: route, parse, validate, middleware, execute, Present and serialize. Attributes identify the tool and action, whether it was destructive or read-only, and the semantic error class. The framework separates an agent mistake from an upstream failure and from a Vinkius-side failure, which makes a reliability dashboard actionable instead of a single red counter.

Wire the tracer to your OpenTelemetry exporter at the boundary. MCP Fusion owns the span vocabulary; your exporter owns where the spans go.

Telemetry and cost

The telemetry collector records the metadata the governance system needs: redaction paths, firewall decisions, rate-limit decisions, audit status, token profile, sandbox result and state transitions. Token Economics adds estimated input and output inflation, overhead ratio and risk classification. These are estimates based on JSON-shaped text, not provider billing claims; the point is comparing a change with the previous contract.

Security of observability

Audit events hash arguments with SHA-256 when hashArgs is enabled. The framework emits events to your sink; it does not claim that the OSS sink is a tamper-proof Ed25519 chain. On Vinkius Cloud, the hosted connector adds the signed audit trail and console retention. That boundary matters in a compliance review.

Never log ctx, credentials, raw authorization headers or full tool arguments. Observe identity class, tenant hash, tool name, duration, status and a digest. The built-in events follow that principle, but a custom sink can still leak what you put into it.

Production wiring

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

Attach at startup, not inside a handler. The registry propagates sinks to existing builders and to builders registered later. When tracing and debug are both active, the framework gives tracing precedence for the overlapping diagnostic path.

Next steps

• Performance: what is precompiled and what costs a request
• Introspection: metadata without a client call
• Contracts: turn observability into a release gate