MCP Observability: Logs, Metrics, Traces, Sessions, and Workflow Outcomes

MCP observability is the practice of connecting protocol events, tool execution, client behavior, and workflow outcomes into one investigation path. It lets an engineer move from “the agent failed” to the exact tool, argument shape, dependency, retry, or authorization step that caused the failure.

What makes MCP observability different

The caller is often a non-deterministic agent. It chooses tools at runtime, may call several tools in sequence, and may recover from an error or silently abandon a task. The server sees protocol traffic, but the reason for a choice may live in another process. That makes correlation and workflow context essential.

The MCP observability stack

• Transport health: connection failures, authorization responses, request duration, and availability.
• Protocol health: discovery, catalog changes, supported versions, and malformed envelopes.
• Tool health: call volume, tool-level errors, validation failures, retries, and latency percentiles.
• Session health: ordered calls, drop-off points, reconnects, and client-specific behavior.
• Outcome health: completed workflows, failed workflows, human handoffs, and business events.

Why a green HTTP status is not enough

MCP tool execution errors can be represented in the response content while the outer transport still succeeds. A status-code-only alert can therefore stay green while the agent receives an error, retries, and gives up. Parse the protocol result and record tool-level failure separately from transport failure.

{
  "content": [{
    "type": "text",
    "text": "to: expected array"
  }],
  "isError": true
}

The dimensions that make telemetry useful

A metric without dimensions is a warning light. The following dimensions turn it into a queue of investigations.

• service and environment: separate production from staging and one server from another.
• client name and version: compare Claude, Cursor, ChatGPT, custom agents, and unknown clients.
• tool name and protocol method: distinguish catalog discovery from execution.
• session or trace identity: reconstruct the order of calls.
• outcome class: success, tool error, validation error, timeout, authorization failure, or transport failure.
• duration percentile: use p50 for typical behavior and p95 for the tail that damages workflows.

From a tool trace to a fix

Start with the incomplete workflow, not the largest log file. Identify the last successful step, the first repeated or failed step, and whether the agent changed arguments. Then inspect the tool schema, dependency latency, error text, permissions, and client mix at that exact point.

• Same arguments repeated: likely a schema mismatch or an error the agent cannot act on.
• Different arguments after a failure: the agent may be recovering; inspect whether the second attempt succeeds.
• One tool dominates incomplete sessions: prioritize that tool even if its overall error rate looks modest.
• Only one client fails: compare its transport, auth, catalog, and argument behavior before changing the server globally.

OpenTelemetry and MCP-specific context

OpenTelemetry is useful for exporting traces and connecting MCP work to downstream services. Add MCP attributes such as client, tool, method, session or trace identity, outcome class, and redaction status. Avoid putting secrets or unrestricted payloads into span attributes. A general trace should lead to the MCP event, and the MCP event should lead to the application dependency that actually failed.

Design for failure and privacy

Telemetry should be fail-open: if the analytics endpoint is unavailable, the tool call should still run. Batch low-value events, bound queue size, redact locally, and expose a clear way to disable payload capture. Treat trace search and operator dashboards as a separate trust boundary from agent-visible context.

A practical minimum dashboard

• Overview: active clients, tool calls, tool-error rate, p95 latency, and completed workflows.
• Clients: client distribution, new versus returning usage, and completion by client.
• Tools: calls, adoption breadth, success rate, p95, retries, and unused tools.
• Sessions: ordered tool paths, incomplete-session drop-off, and top failure points.
• Investigations: raw event metadata, redacted arguments, result state, and downstream correlation IDs.

Frequently asked questions