可观测性
MCP 请求会与模型流量一起出现在访问日志、用量事件管道和 Prometheus 指标中。MCP 专用字段会标识 JSON-RPC 操作、调用的工具、发现结果和工具调用结果。
使用访问日志调查单个请求，再使用用量事件和指标监控工具调用流量。限流和安全护栏阻断都会出现在这些信号中。在 AISIX Cloud 中，预算 拒绝也会出现在这里。
访问日志
AISIX 处理完发往 /mcp 或 /mcp/{server} 的请求后，会写入访问日志。身份认证失败发生在访问日志写入之前。标准字段提供请求状态、延迟、调用方 API Key ID 和请求 ID；MCP 专用字段说明具体操作：
| 字段 | 出现条件 | 值 |
|---|---|---|
mcp_method | 请求体是包含方法的单个 JSON-RPC 对象。 | 方法，例如 initialize、tools/list 或 tools/call；在 UTF-8 字符边界截断为 256 字节。即使不受支持的协议版本导致请求提前返回 400，AISIX 也会记录该字段。 |
mcp_tool | 方法为 tools/call 且存在 params.name。 | 客户端发送的工具名称；在 UTF-8 字符边界截断为 256 字节。 |
tools_total | AISIX 处理 tools/list 请求。 | 访问策略过滤前，从查询成功的上游服务器返回的工具数量。请求被更早的检查拒绝时，该字段不存在。 |
tools_returned | AISIX 处理 tools/list 请求。 | 访问策略过滤后返回给调用方的工具数量。请求被更早的检查拒绝时，该字段不存在。 |
AISIX 无法推导的字段会被省略。例如，批量请求或 AISIX 无法解析的请求体没有 mcp_method。访问日志绝不会包含工具参数或结果。
诊断空工具列表
当 tools/list 没有返回工具时，请比较两个工具计数和附近的告警：
| 观察结果 | 可能原因 | 检查项 |
|---|---|---|
tools_total 大于零、tools_returned 为零，并出现 no MCP access policy or key-level grant applies 告警。 | 调用方没有访问授权。 | 为调用方添加访问授权。 |
tools_total 大于零、tools_returned 为零，并出现 exclude every upstream tool 告警。 | 授权存在，但过滤掉了所有发现的工具。 | 修正适用的允许列表、拒绝列表或匿名允许列表。 |
出现 skipping upstream in tools/list: list_tools failed 告警。 | 指定上游失败，但 AISIX 继续查询其它上游。该上游的工具不会计入任何一个计数。 | 检查该服务器的可达性、身份认证和协议配置。 |
| 两个计数都为零，且没有上游失败告警。 | 查询成功的上游均未返回工具。 | 检查是否至少有一个已启用并公开工具的上游。 |
日志收集、标准字段和请求 ID 关联方式请参见访问日志与请求关联。
用量事件
tools/call 请求是否产生用量事件取决于 AISIX 已处理到哪个阶段：
| 结果 | 用量事件 |
|---|---|
AISIX 在工具调用核算前拒绝请求，例如身份认证失败、指定了未知服务器、请求体 无法读取或过大、JSON 无效、AISIX 无法解析 params 的结构，或协议版本不受支持。 | 不发出。 |
| 请求进入工具调用核算。 | 即使缺少 params 或工具名称，或之后被访问控制、限流、安全护栏、AISIX Cloud 预算或 MCP 协议处理器拒绝，也会发出。 |
如果 AISIX 读取或缓冲 MCP 响应体时失败，可能会在事件发出前返回。因此，用量遥测覆盖上述可识别结果，而不是每个已识别的工具调用。握手和发现方法不产生用量事件。
事件会标识调用方、服务器、工具、结果和耗时：
| 字段 | 值 |
|---|---|
inbound_protocol | mcp |
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 记录与其它网关流量保持一致；在其它流量中，重试和网关处理可能使两者不同。
基础用量事件不包含工具参数或结果。启用完整内容采集后，通过流量控制和输入安全护栏检查的 tools/call 可以在完成数据脱敏后导出 params.arguments。如果响应包含 JSON-RPC result，导出器也可以采集该结果。输出安全护栏阻断会抑制这两个字段，其它 MCP 方法不会被采集。请参见配置内容采集。
MCP 用量事件会通过与模型用量事件相同的路径投递。所有已配置的可观测性导出器都会收到这些事件，因此 MCP 流量会与其它网关流量一起出现在导出链路中。在 AISIX Cloud 中，这些事件也会流入控制面的用量接收端。
指标
MCP 请求会出现在网关的 Prometheus 指标中，并携带可用于区分模型流量的标签。使用下列标签筛选相关指标序列：
| 目标 | 指标 | 过滤条件 |
|---|---|---|
| 跟踪活跃 MCP 请求。 | aisix_proxy_in_flight_requests | inbound_protocol="mcp" |
| 检查 MCP 用量事件投递。 | aisix_usage_events_emitted_total | handler="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_requests | inbound_protocol="mcp" |
aisix_usage_events_emitted_total | handler="mcp" 和 inbound_protocol="mcp" |
下一步
你现在已经了解如何通过访问日志诊断 MCP 请求，以及工具调用会出现在用量事件和指标中的哪些位置。使用下面的指南查看完整指标目录，或调整产生这些信号的流量：