Research guide · MCP · observability · agent operations
MCP tool-call health: observe agent runs without inventing protocol sessions
A public MCP server can look healthy at the request level while agents still fail at the workflow level. If you only record tool name, outcome and latency, you can miss the important pattern: an agent repeatedly calls a valid tool before satisfying an application prerequisite, recovers after an error, loops, or disappears. The useful unit is not an invented protocol session. It is an explicit application run correlated with each MCP request.
Published 15 September 2026 · current MCP revision checked against 2026-07-28
Current protocol boundary
MCP 2026-07-28 removed protocol-level sessions
The current MCP revision removed protocol-level sessions and the Mcp-Session-Id header from Streamable HTTP. Servers that need state across calls use explicit server-minted handles passed as ordinary tool arguments. Each request carries its own protocol and capability metadata.
That makes a game match, procurement job, research task, checkout attempt or workflow an application object. Treat it as one. Do not infer a durable workflow from connection reuse, an SSE lifetime or an obsolete session header.
Correlation model
Track request, trace, run and business outcome separately
- Request ID. One protocol invocation. Never assume it identifies the whole agent run.
- Trace ID. Connect the gateway, MCP handler and downstream API, database, payment or storage spans.
- Run handle. Your server-minted task, match, job or workflow identifier when cross-call application state is required.
- Client and protocol version. Record the client identity when supplied so failure patterns can be segmented by caller and version.
- Tool and release. Record the tool name plus a stable server or tool version.
- Outcome class and reason code. Keep protocol failures distinct from validation, authentication, authorization, application preconditions, downstream errors, cancellation and success.
- Sequence and latency. Record where the call sits in the application run and how long it took.
The important distinction
A valid MCP call can still fail because the agent is in the wrong application state
Suppose an agent calls make_move before it has created an identity or selected a match. If the JSON-RPC request is valid and reaches the handler, but the handler rejects it because required application state is absent, classify that as an application precondition failure rather than a generic MCP error.
Stable reason codes such as identity_required or match_not_selected make the pattern measurable across clients and releases. They also tell you whether the likely fix is protocol compatibility, tool affordance design, prerequisite discovery or agent reasoning.
Run-shape metrics
Measure recovery and completion, not raw errors alone
Run completion rate
Share of application runs that reach a defined successful terminal state.
Precondition failure rate
Protocol-valid calls that arrive before identity, authorization, selection or another required state.
Recovery after error
Failed calls followed by a successful corrective call in the same run.
Retry-loop rate
Repeated same-tool or same-reason failures beyond a small threshold.
Abandonment after error
Runs with no subsequent useful call after a failure.
Client and version split
Compare outcomes and latency by client identity, protocol version and server release.
Progress
Use progress tokens for request progress, not as your business workflow database
MCP supports optional progress notifications for long-running requests. A client that wants progress supplies a unique progressToken for the active request and the server may report progress against it. That is useful telemetry, but it remains request-scoped.
If a workflow spans multiple tool calls, keep your own application run handle and correlate each request back to it. This preserves the protocol boundary while still giving operators the sequence view they need.
Privacy
Observability should not become credential collection
Do not log bearer tokens, API keys, wallet private material, payment signatures or raw sensitive tool arguments merely to reconstruct a run. Prefer opaque handles and stable reason codes. Keep diagnostic payload capture explicit, short-lived and access-controlled.
Separate independent external calls from your own probes, uptime checks and verification traffic so monitoring does not quietly become the largest apparent user of the server.
Demand signal
A fresh operator question shows why request-level logs are not enough
A public r/mcp question posted on 15 September 2026 describes thousands of tool calls across several clients and asks how to understand the shape of a run when many calls fail because agents act before they have identity or other prerequisite state. That community report is the demand signal for this guide; the protocol claims here are grounded in the current MCP specification.
Primary sources
Continue