Metrics

AI Gateway instruments every MCP method call automatically, no instrumentation required in the agent or the upstream server. To collect a metric, add its name to the telemetry.metrics property in your zilla.yaml config. The metrics can then be collected and exported via exporters, such as Prometheus.

Metric	Type	Description
mcp.initialize	counter	The number of initialize requests handled.
mcp.initialize.duration	histogram	The duration of initialize requests in nanoseconds.
mcp.tools.list	counter	The number of tools/list requests handled.
mcp.tools.list.duration	histogram	The duration of tools/list requests in nanoseconds.
mcp.tools.call	counter	The number of tools/call requests handled.
mcp.tools.call.duration	histogram	The duration of tools/call requests in nanoseconds.

telemetry:
  metrics:
    - mcp.initialize
    - mcp.initialize.duration
    - mcp.tools.list
    - mcp.tools.list.duration
    - mcp.tools.call
    - mcp.tools.call.duration

You can also enable every MCP metric at once with the mcp.* wildcard, which is useful while a gateway is still adding new MCP methods such as prompts/list or resources/list:

telemetry:
  metrics:
    - mcp.*

Attributes

Add telemetry.attributes to an mcp · server binding to dimension its metrics by the MCP method, the tool being called, and the outcome of the call. Each attribute value is a variable populated by the gateway per request:

north_mcp_server:
  type: mcp
  kind: server
  exit: north_mcp_proxy
  telemetry:
    attributes:
      method: ${mcp.method}
      tool: ${mcp.tool}
      outcome: ${mcp.outcome}

Attribute	Description
method	The MCP method invoked, such as initialize, tools/list, or tools/call.
tool	The name of the tool being called, when the method is tools/call.
outcome	Whether the call succeeded or failed.

Use the zilla metrics command to see the raw metrics that AI Gateway has collected.

Tips

The synthetic tools Tool Discovery adds, zilla__search_tools, zilla__describe_tool, and zilla__execute_tool, are ordinary tools from the metrics system's point of view. A call to any of them counts toward mcp.tools.call and its duration histogram with tool set to the tool's own name, the same as any other tools/call.

Detecting Issues

Each metric points at a different layer of the pipeline, depending on which one moves and how it's dimensioned:

• mcp.tools.call failures isolated to one tool (outcome attribute): that upstream or toolkit is degraded, not the gateway itself. See Why does a tool call route to the wrong upstream, or fail to route at all?
• Rising mcp.tools.list.duration with no connectivity events in the logs: cache or store latency, not an upstream problem. See Listing Cache and, for a multi-replica deployment, the shared-store guidance in Scale MCP Gateway.
• Rising mcp.initialize counts without a matching rise in traffic: session churn. Cross-check against BINDING_MCP_SESSION_ESTABLISHED/BINDING_MCP_SESSION_CLOSED in the logs to confirm whether sessions are opening and closing more often than expected.

There's no rate-limiting or throttling binding today, so a volume spike on mcp.tools.call by itself isn't something the gateway can act on directly, it's a signal to look at the upstream tool provider, not a gateway-side control.

See Troubleshooting Guides for the full symptom-to-fix reference.