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, budgets, and guardrail blocks appear in the same observability tools you already use for model traffic.
Usage Events
Every MCP tools/call emits one usage event into the same sink as model usage. This includes calls rejected by rate limits, budgets, or guardrails, 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. |
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. |
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.
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. In managed deployments, they flow to the same usage sink as model traffic. They also fan out to any configured OTLP, SLS, or Datadog exporters, so MCP traffic appears alongside the rest of your gateway traffic.
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 | endpoint="/mcp" and 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 limits, concurrency limits, and budgets to MCP tool calls.
- Guardrails: inspect MCP tool arguments and results.