Observability

Every MCP tools/call emits a usage event and updates the gateway's request metrics on the same pipelines as model traffic. Both are tagged with an MCP protocol marker, so you can isolate MCP tool traffic without a separate telemetry stack. Rejected calls — rate-limited, budget-exceeded, or guardrail-blocked — emit events too, so telemetry reflects every attempt, not only successful calls.

Usage Events

Each tool call emits one usage event into the same sink as model usage. The event carries:

Field	Value
inbound_protocol	mcp
mcp_server_name	The registered server the tool belongs to.
mcp_tool_name	The upstream tool name that was called.
api_key_id	The caller API key that made the call.
status_code	The call's outcome status.
latency_ms	End-to-end tool-call latency.
guardrail_blocked	true when a guardrail blocked the call's input or output.
request_id, occurred_at	Correlation id and timestamp.

Token and cost fields are zero for MCP tool calls, because a tool call carries no model tokens. Use mcp_server_name and mcp_tool_name for per-tool call-volume attribution rather than token or spend analytics.

The event records the server and tool names and the outcome — it does not include the tool arguments or the tool result. MCP content capture is a separate surface from usage telemetry.

MCP usage events are delivered on the same paths as model usage events:

• In AISIX Cloud managed deployments, they flow to the control-plane usage sink alongside model usage.
• They also fan out to any per-environment OTLP, SLS, or Datadog exporters you configure, so MCP tool traffic appears in the same exporters as the rest of your gateway traffic.

Metrics

MCP requests appear in the gateway's Prometheus metrics, tagged so you can filter them out from model traffic:

• On the in-flight request gauge aisix_proxy_in_flight_requests, MCP requests carry endpoint="/mcp" and inbound_protocol="mcp".
• The usage-emission counter aisix_usage_events_emitted_total tags MCP events with handler="mcp".

Metrics are exposed on GET /metrics through the dedicated metrics listener. For the full metric catalog and label semantics, see Metrics Reference.

Verification

Send one MCP tool call through the gateway, then scrape the metrics endpoint:

curl -sS "http://127.0.0.1:9090/metrics" | grep 'inbound_protocol="mcp"'

Expected result: the output includes series tagged inbound_protocol="mcp", and aisix_usage_events_emitted_total shows a handler="mcp" sample. Adjust the address to match your observability.metrics.prometheus.addr. Metric families register on first observation, so send a tool call before scraping.

Next Steps

• Metrics Reference — the full metric catalog, labels, and MCP notes.
• Guardrails — blocked tool calls surface with the guardrail_blocked flag set.
• Rate Limits and Budgets — rejected tool calls emit events with the rejection status.