Observability
MCP tool calls use the same telemetry pipelines as model traffic. Usage-event fields identify the caller, upstream server, tool, and outcome, while Prometheus labels let you separate MCP traffic from model traffic.
Use these signals to measure tool-call volume and monitor failures. Rate limits and guardrail blocks appear in the same observability tools you already use for model traffic. In AISIX Cloud, budget rejections appear there as well.
Usage Events
Every MCP tools/call emits one usage event into the same sink as model usage. This includes calls rejected by rate limits or guardrails, and by budgets configured through AISIX Cloud, so telemetry reflects every tool-call attempt, not only successful calls.
The event identifies the caller, server, tool, outcome, and timing:
| Field | Value |
|---|---|
inbound_protocol | mcp |
mcp_server_name | The registered server the tool belongs to. |
mcp_tool_name | The upstream tool that was called. |
api_key_id | The caller API key that made the call. |
status_code | The call's outcome status. |
upstream_latency_ms | Time spent on the upstream tool call. |
downstream_latency_ms | Total time the caller waited for the tool call. |
guardrail_blocked | true when a guardrail blocked the call's input or output. |
request_id, occurred_at | Correlation id and timestamp. |
MCP tool calls do not carry model tokens, so token and cost fields remain zero. Use mcp_server_name and mcp_tool_name for per-tool call-volume attribution rather than token or spend analytics.
MCP currently makes a single upstream attempt that spans the request, so upstream_latency_ms and downstream_latency_ms report the same duration. The separate fields keep MCP records consistent with other gateway traffic, where retries and gateway processing can make the two values differ.
The event records the server name, tool name, and outcome. It does not include tool arguments or tool results. MCP content capture is a separate surface from usage telemetry.
MCP usage events follow the same delivery paths as model usage events. Any configured observability exporter receives them, so MCP traffic appears alongside the rest of your gateway traffic. In AISIX Cloud, they also flow to the control plane's usage sink.
Metrics
MCP requests appear in the gateway's Prometheus metrics with labels that distinguish them from model traffic. Use the labels below to filter the relevant metric series:
| Goal | Metric | Filter |
|---|---|---|
| Track active MCP requests. | aisix_proxy_in_flight_requests | inbound_protocol="mcp" |
| Check MCP usage-event emission. | aisix_usage_events_emitted_total | handler="mcp" and inbound_protocol="mcp" |
Metrics are exposed on GET /metrics through the dedicated metrics listener. For the full metric catalog and label semantics, see Metrics Reference.
Verify Metrics
To verify that MCP metrics are emitted, send one MCP tool call through the gateway, then scrape the dedicated metrics listener. The example below uses the default listener address and path. If your startup configuration sets a different observability.metrics.prometheus.addr, use that address instead.
Metric families register on first observation, so the MCP series appears only after a tool call is recorded:
curl -sS "http://127.0.0.1:9090/metrics" | grep 'inbound_protocol="mcp"'
The output should include metric samples with these labels:
| Metric | Label |
|---|---|
aisix_proxy_in_flight_requests | inbound_protocol="mcp" |
aisix_usage_events_emitted_total | handler="mcp" and inbound_protocol="mcp" |
Next Steps
You now know where MCP tool calls appear in usage events and metrics. Use these guides to review the full metric catalog or adjust the traffic that produces those signals:
- Metrics Reference: review the full metric catalog and label semantics.
- Rate limits and budgets: apply request and concurrency limits, and configure AISIX Cloud budgets for MCP tool calls.
- Guardrails: inspect MCP tool arguments and results.