跳到主要内容

可观测性

MCP 工具调用使用与模型流量相同的遥测链路。用量事件字段会标识调用方、上游服务器、工具和结果；Prometheus 标签可帮助你将 MCP 流量与模型流量区分开。

可以使用这些信号衡量工具调用量并监控失败。限流和安全护栏阻断会出现在你已经用于模型流量的同一套可观测性工具中。在 AISIX Cloud 中，预算拒绝也会出现在这里。

用量事件​

AISIX 仅在请求进入 tools/call 用量核算后才生成一条用量事件。在此之前被拒绝的请求不会产生事件，包括认证失败、指定了未知服务器、请求体无法读取或过大、JSON 无效或 AISIX 无法解析 params 的结构，以及协议版本不受支持。

请求进入该核算路径后，即使缺少 params 对象或工具名称，AISIX 仍会记录这次调用。之后因访问控制、限流、安全护栏、AISIX Cloud 预算或 MCP 协议处理器而被拒绝的调用也会被记录。如果 AISIX 随后读取或缓冲 MCP 响应体时失败，可能会在事件发出前返回。因此，用量遥测覆盖的是上述可识别结果，而不是每个已识别的工具调用。它也不覆盖 MCP 握手或发现方法，以及在进入工具调用用量核算前被拒绝的请求。

事件会标识调用方、服务器、工具、结果和耗时：

字段值
inbound_protocolmcp
mcp_server_name工具所属的已注册服务器。
mcp_tool_name被调用的上游工具。
api_key_id发起调用的调用方 API Key。
status_code调用结果状态。
upstream_latency_ms上游工具调用所花费的时间。
downstream_latency_ms调用方等待工具调用完成的总时间。
guardrail_blocked当输入或输出被安全护栏阻断时为 true。
request_id、occurred_at关联 ID 和时间戳。

MCP 工具调用没有模型 Token，因此 Token 和成本字段为零。需要按工具归因调用量时，请使用 mcp_server_name 和 mcp_tool_name，而不是依赖 Token 或花费分析。

MCP 目前只执行一次贯穿整个请求的上游尝试，因此 upstream_latency_ms 和 downstream_latency_ms 会报告相同的时长。保留两个独立字段可使 MCP 记录与其它网关流量保持一致；在其它流量中，重试和网关处理可能使两者不同。

事件会记录服务器名称、工具名称和调用结果，但不会包含工具参数或工具结果。MCP 内容捕获与用量遥测是不同的能力边界。

MCP 用量事件会通过与模型用量事件相同的路径投递。所有已配置的可观测性导出器都会收到这些事件，因此 MCP 流量会与其它网关流量一起出现在导出链路中。在 AISIX Cloud 中，这些事件也会流入控制面的用量接收端。

指标​

MCP 请求会出现在网关的 Prometheus 指标中，并携带可用于区分模型流量的标签。使用下列标签筛选相关指标序列：

目标指标过滤条件
跟踪活跃 MCP 请求。aisix_proxy_in_flight_requestsinbound_protocol="mcp"
检查 MCP 用量事件投递。aisix_usage_events_emitted_totalhandler="mcp" 和 inbound_protocol="mcp"

指标通过专用指标监听器的 GET /metrics 暴露。完整指标目录和标签语义请参见指标参考。

验证指标​

要验证 MCP 指标是否发出，请先通过网关发送一次 MCP 工具调用，然后抓取专用指标监听器。下面的示例使用默认监听地址和路径。如果你的启动配置设置了其它 observability.metrics.prometheus.addr，请使用对应地址。

指标族会在首次观测后注册，因此只有记录过工具调用后才会出现 MCP 序列：

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

输出中应包含带有以下标签的指标样本：

指标标签
aisix_proxy_in_flight_requestsinbound_protocol="mcp"
aisix_usage_events_emitted_totalhandler="mcp" 和 inbound_protocol="mcp"

下一步​

你现在已经了解 MCP 工具调用会出现在用量事件和指标中的哪些位置。使用下面的指南查看完整指标目录，或调整产生这些信号的流量：

  • 指标参考：查看完整指标目录和标签语义。
  • 限流与预算：对 MCP 工具调用应用请求限制和并发限制，并配置 AISIX Cloud 预算。
  • 安全护栏：检查 MCP 工具参数和工具结果。