Keep the Capability Snapshot Beside the MCP Trace

request: r-214
protocol context: missing
observed: a tool-related request was rejected
conclusion: unavailable

That is an abstract diagnostic note, not a wire transcript. It preserves an outcome but loses the context needed to interpret it. The server may not have advertised the feature. The client may not have declared a capability needed for the interaction. Or the capture may simply omit the relevant context. From the note alone, those cases collapse into one failure.

A trace can preserve the symptom and lose the contract

A request and its error do not answer a more basic question: which protocol version and capabilities applied to that request?

Without that answer, absence becomes dangerously easy to narrate. No tool-shaped event appears, so perhaps tools were unavailable. A resource update is missing, so perhaps subscriptions failed. A server does not ask for client input, so perhaps the client could not provide it. Each reading may be plausible, but the trace cannot distinguish “not supported,” “not exercised,” and “not captured.”

The practical fix is to keep a capability snapshot beside the trace. For current MCP traffic, that snapshot must be request-scoped. It should preserve what was observed without rewriting the event sequence or filling gaps from configuration as if they were captured facts.

What belongs in a current snapshot

The MCP architecture dated 2026-07-28 describes MCP as stateless: every request is self-contained and carries its own protocol version and capabilities. A host may manage multiple clients, while each client communicates with exactly one server. Capabilities unlock features on a per-request basis.

That changes the debugging unit. Preserve the client-server pair, the request identifier used by the local observability system, the protocol version carried for that request, the client’s declared capabilities, and the server capability evidence that was actually observed. If server discovery was not captured, record that gap; do not manufacture a declaration from a later configuration file.

Unknown or extension-specific entries should remain unknown. Capture time and redaction notes matter too, because an unexplained omission can make a clean snapshot look more complete than it is. The most important label is still observed versus inferred.

This is an engineering design for diagnostics, not an MCP logging schema. The current architecture describes request context and capability behavior; it does not prescribe trace field names, storage layout, or a wire-event order for observability systems.

A time-bound note for older traces

Traces produced under the 2025-06-18 architecture revision need different context. That revision described MCP as stateful, with one client session per server and capability exchange during initialization. For those historical traces, a session-level snapshot and the observed initialization boundary can be necessary to explain later messages.

That statement is deliberately limited to the 2025-06-18 revision. It must not be projected onto current MCP traffic, where version and capability context is per request.

Read failures against the architecture that produced them

With a current request snapshot, the rejection in the opening note becomes a bounded investigation. If the required server capability was not observed for that request, unsupported behavior is one possibility. If it was observed, inspect the request and response path. If capability evidence is missing, the correct status is incomplete evidence—not a confident story about either participant.

The same rule applies when comparing runs: first confirm that the protocol revision and request capability context are comparable. Otherwise the most visible event difference may be downstream of a quieter context difference.

If you had to reopen a failed MCP request six months later, what would you insist on finding in its capability snapshot?

For cross-run analysis, the capability snapshot is more useful as a join key than as a free-form annotation. Canonically order the observed capability entries, preserve unknown extensions, include the protocol version and observed-versus-inferred labels, then hash that representation.

That creates an explicit comparison boundary. Two traces belong in the same baseline only when their protocol revision, snapshot hash, and capture-completeness state are compatible. Otherwise an aggregate failure rate can mix different contracts and hide the reason the runs diverged.

A simple presence matrix is often enough: one row per request, columns for required capability observed, feature exercised, relevant event captured, and outcome. The matrix keeps “unsupported,” “not exercised,” and “not captured” as separate data states instead of forcing all three into a single null value.