MCP analytics
Every authenticated MCP request the Zuplo MCP Gateway handles produces a set of structured analytics events. The events power the MCP tab on the Zuplo Portal's Analytics page and feed the same data into Zuplo's standard log and metrics pipelines. This page explains why each event exists, the dimensions that scope the data, and the operational questions the dashboard exists to answer.
What the analytics are for
A platform team running an MCP Gateway usually wants to answer a small number of recurring questions:
- Is the gateway healthy right now? What's the success rate, and where are the failures coming from — the gateway, the upstream, or the client?
- Which capabilities (tools, prompts, resources) are users actually exercising, and which are slow or error-prone?
- Who is using the gateway and how heavily?
- Did the upstream OAuth flow finish for the user who just complained, or did they hit a connect-required state nobody resolved?
- When latency went up, was it the gateway or the upstream?
The analytics event taxonomy is shaped to answer each of those questions without leaving the dashboard.
The three event families
Every MCP analytics event belongs to one of three families. The split matters because each family answers a different kind of question.
mcp_requestevents fire at the route boundary. They record the acceptance or rejection of an inbound MCP request before any JSON-RPC routing happens — what authentication and authorization decisions the gateway made and why. These are the events that tell you "the gateway rejected this request" versus "the gateway accepted it and something downstream went wrong."capability_invocationevents fire on every parsed JSON-RPC call. They record what the client asked for (themcpMethodandcapabilityName) and what happened — success, error, latency. This family feeds the top-capabilities tables and the per-tool error-rate views.auth_evententries record the OAuth lifecycle: tokens issued and validated, consent approvals, upstream connections established, and token revocations. This family powers the "did the user actually finish OAuth" question.
Together the three families let an operator pivot from a failed tool call to the OAuth event that issued the token, to the request boundary that accepted the request, without leaving the analytics surface.
Outcomes drive the chart colors
Every event carries an outcome value in one of seven classes — success,
failure, denied, application_error, connect_required, partial,
cancelled. Outcome class drives chart colors and the success-rate KPI.
Failures break down further by failureOrigin (gateway, upstream, client) for
the failure-origin chart and KPI.
The split between denied, application_error, and failure matters: a 401 on
the route is a denied, an upstream returning an MCP-level error inside a 200
response is an application_error, and an actual operational failure (timeout,
network error, malformed response) is a failure. The operator sees the same
red chart slice in all three cases but can pivot to the right next question by
clicking the slice.
Dimensions you'll filter by
Each event carries the route and identity fields that scope it:
operationId(surfaced asvirtualServerName) — the route's identityupstreamServerId(surfaced asupstreamServerName) — the upstream's idsubjectId— the authenticated userauthProfileIdandupstreamAuthMode— which OAuth surface produced the callhttpMethod,transport,mcpMethod,clientName— protocol shapelatencyMs, with the gateway and upstream slices when both halves are measuredreasonCodeanderrorTypeon failure events — stable programmer-friendly strings likemissing_token,invalid_audience,connect_required,upstream_timeout
Reason codes appear in both analytics events and the structured-log counterparts, which lets a single string cross-reference the two data sources when an operator is debugging.
The dashboard's drill-in model uses these dimensions. Clicking any value in a breakdown table (a user, an upstream, a capability) scopes the entire dashboard to that value; clicking again toggles the filter off. Multiple drill-ins compose with AND semantics — clicking a user, then an upstream, then a capability type narrows the view to that combination.
How the dashboard answers each question
The Portal renders the MCP analytics in a fixed order so the layout doesn't reshape when filters or time ranges change. The order maps to the recurring operator questions.
The headline cards across the top — total events, success rate, p95 latency, and failure origin decomposition — answer "is the gateway healthy?" at a glance. The latency card splits gateway and upstream slices beneath the p95 number, which is the fastest way to tell "the gateway is slow" from "the upstream is slow."
The Events Over Time chart breaks volume down by event family and outcome, with failure outcomes always rendered in red. An error spike has a characteristic shape — a red bar appearing in a previously-green window — that's easy to spot on the chart and click into.
The capability tables — Top Capabilities (with view toggles for Most Calls, Most Errors, and Slowest) and the per-type filter (Tool, Resource, Prompt) — answer "what are users actually doing?" and "what's broken?" An operator can pivot from a slow tool to its server-and-type drill-in with one click, narrowing the dashboard to that capability across every other view.
The Top Users table groups by subjectId, with email-style subjects rendered as
the email (so auth0|google-apps|alex@example.com shows as alex@example.com)
and other subject formats shown as-is. It's the fastest path from "alex says the
gateway is broken" to alex's failed events.
The Top MCP Routes and Top Upstream Servers tables sit side by side. They track
together for most projects because each route proxies one upstream; the split
shows up when one upstream sits behind multiple routes (for example, a
full-featured route and a read-only one). The MCP Methods, Top Clients, and
Transport panels add a final layer of protocol-shape detail: which JSON-RPC
methods are flowing, which clients identified themselves at initialize, and
which transport they used.
The JSON-RPC Error Codes and Failure Origins panels decompose failures so an
operator can answer "is this our problem, theirs, or the client's?" without
leaving the dashboard. The Top Reason Codes table at the bottom is the most
direct path into structured logs — the same reasonCode value appears on both
surfaces.
Where to find it
The MCP analytics dashboard is a tab on the Zuplo Portal's Analytics page. At the account scope, Analytics → MCP aggregates across every project on the account that has MCP routes. At the project scope, Analytics → MCP shows that project's events only.
The MCP tab appears automatically once any MCP request has been recorded for the project. New projects show the empty state until the first MCP request lands.
Reference: event types
The dashboard is built from a fixed set of event types. New types may be added over time, but the families and outcome classes above stay stable.
mcp_request
Boundary events at the MCP route. Examples include mcp_request_accepted and
mcp_request_rejected. Carries operationId, subjectId (when known),
httpMethod, transport, the reasonCode on rejection, and the latencyMs
spent at the boundary.
capability_invocation
Per-capability events emitted by
McpProxyHandler. Each invoked call
emits two events: an mcp_capability_invoked event before the upstream fetch
(carrying the parsed mcpMethod and capabilityName), and an
mcp_capability_completed event afterward (carrying outcome, mcpStatus,
latencyMs, and any JSON-RPC error details).
auth_event
OAuth and upstream-auth lifecycle events. Examples include
mcp_auth_downstream_token_issued, mcp_auth_downstream_token_validated,
mcp_auth_upstream_connection_established, and mcp_auth_consent_approved.
Carries the same identity fields as the other families when applicable, plus
authProfileId and upstreamAuthMode.
Forwarding the underlying data
The same events that back the dashboard also flow through Zuplo's standard analytics pipeline. Every event corresponds to a structured log entry — see Logging for the MCP-specific log fields. Log destinations supported include Datadog, AWS CloudWatch, Google Cloud Logging, Splunk, Sumo Logic, New Relic, Loki, Dynatrace, and VMware Log Insight; see Logging for the full list of destinations and how to enable them.
For metrics, see the built-in metrics plugins (Datadog, Dynatrace, New Relic, OpenTelemetry). The OpenTelemetry plugin specifically exports traces and logs for the MCP request, every inbound policy, the handler, and the upstream fetch.
Related
- Logging — the structured-log counterpart, including the field model and OpenTelemetry export.
McpProxyHandlerreference — the handler whose capability instrumentation drives the dashboard's top-capability views.- Troubleshooting — the operator playbook when an analytics chart shows something concerning.