MCP 可观测性：监控 AI 智能体的每次工具调用

更新时间 8/14/2026

核心要点

  • MCP 可观测性必须识别调用方、注册的 Server、工具、结果与延迟，而不能只看每个请求共用的 HTTP 端点。
  • 每次 tools/call 尝试都会由 AISIX AI Gateway 生成一条用量事件，其中包括被限流、防护规则和适用的 AISIX Cloud 预算拒绝的调用。
  • 用量事件包含 MCP 专用的 Server 和工具字段，但有意排除工具参数与结果。
  • MCP 调用不包含模型 Token，因此 Token 和成本字段保持为零；工具调用量应通过调用事件而不是 Token 仪表盘计量。
  • Prometheus 标签可以区分 MCP 流量与模型流量，并显示进行中的请求和用量事件发送情况。
  • 当前 MCP 链路只发起一次上游尝试，因此不能把延迟数据解读为存在重试或故障转移。

当智能体报告“工具失败”时，这句话不足以支撑 MCP 平台运维。

平台团队需要知道，是哪个调用方发起了尝试、选择了哪个注册 Server 和工具、调用被网关拒绝还是上游失败、调用方等待了多长时间，以及内容策略是否介入。安全团队也需要这些答案，但不应默认把敏感工具参数和结果复制到每条分析记录中。

传统 HTTP 监控必不可少，却无法独立满足需求，因为 MCP 工具调用共用相同的端点与方法。大量请求都以 POST /mcp 到达，真正有意义的操作位于 JSON-RPC 请求体内。支持 MCP 感知的网关必须将这些协议上下文转化为结构化遥测。

AISIX AI Gateway 让 MCP 工具调用使用与模型流量相同的遥测链路，同时通过协议、Server 和工具专属字段进行标记。用量事件提供按尝试维度的详细信息，用于分析和审计；Prometheus 指标提供网关活动及事件链路健康状态的实时视图。二者结合，可以支持事件响应，又不会把载荷留存设为默认行为。

平台团队需要测量哪些内容

有效的 MCP 监控始于问题，而不是仪表盘。生产平台应能回答：

  • 正在尝试多少次工具调用？调用量如何随时间变化？
  • 哪些调用方 API key 产生了最多流量？
  • 哪些已注册 MCP Server 和工具使用最频繁？
  • 哪些调用成功、在上游失败、超过限制或触发防护规则？
  • 当前有多少 MCP 请求正在执行？
  • 上游工具调用耗时多久？调用方等待了多久？
  • 用量事件是否仍在抵达已配置的接收端？

这些问题涵盖三个运维视角。

平台可靠性 关注调用量、并发、延迟、失败率和遥测交付。它帮助团队评估网关与上游服务容量、发现饱和状态并检测回归。

安全运营 关注调用方身份、未授权或被策略阻断的尝试、异常工具选择，以及防护规则活动突然增加。它帮助团队区分集成故障与已被入侵或约束不足的智能体。

产品与容量规划 关注实际使用的工具。工具目录可能包含数百个条目，但用量事件能说明哪些能力真正带来价值，以及哪些高成本依赖需要更严格的限制。

不要把这些视角压缩成一个全局请求计数器。runbooks__search 调用量激增与 payments__create_refund 调用量激增含义截然不同，即使二者都经过同一个 /mcp 端点。

1flowchart LR
2    Agent["MCP 客户端或智能体"] --> AISIX["AISIX AI Gateway"]
3    AISIX --> MCP["MCP Server 或 OpenAPI 工具"]
4    AISIX --> Events["用量事件链路"]
5    AISIX --> Metrics["Prometheus /metrics"]
6    Events --> Analytics["按调用方、Server 和工具分析"]
7    Events --> Audit["事件与策略复盘"]
8    Metrics --> Alerts["实时健康告警"]
9    Metrics --> Ops["网关运维仪表盘"]

这种分工是有意设计的。用量事件携带工具分析所需的详细维度，Prometheus 指标则公开有界的运维时间序列，适合抓取与告警。

AISIX 如何表示 MCP 用量

每次 MCP tools/call 尝试都会生成一条 AISIX 用量事件。成功的上游调用会生成事件，被请求限制、防护规则或覆盖该调用方的 AISIX Cloud 预算在上游前拒绝的调用也会生成。这样，即使没有发起后端请求，策略执行也不会从分析数据中消失。

MCP 专用字段包括：

字段运维含义
inbound_protocol设为 mcp，用于与模型流量区分
mcp_server_name工具所属的已注册 Server
mcp_tool_name被调用的上游工具名
api_key_id对此次尝试负责的调用方 API key
status_code记录的调用结果状态
upstream_latency_ms上游工具调用耗时
downstream_latency_ms调用方观察到的总耗时
guardrail_blocked输入或输出被阻断时为 true
request_id用于排查的关联标识
occurred_at事件时间戳

投射到支持 JSON 的接收端后，一条示例事件可能如下：

1{
2  "inbound_protocol": "mcp",
3  "mcp_server_name": "runbooks",
4  "mcp_tool_name": "search",
5  "api_key_id": "operations-agent-key-id",
6  "status_code": 200,
7  "upstream_latency_ms": 84,
8  "downstream_latency_ms": 84,
9  "guardrail_blocked": false,
10  "request_id": "req-7c8d2f",
11  "occurred_at": "2026-08-14T08:30:00Z"
12}

事件包含身份、路由、结果与时间元数据，但不包含工具参数或工具结果。这条边界降低了把客户数据、凭证、搜索查询或内部记录复制到通用分析链路的风险。AISIX 可以通过防护规则检查流经系统的内容，而不在用量事件中持久化这些内容。

MCP 与模型流量的消耗单位也不同。工具调用没有输入或输出 Token，因此 Token 和成本字段保持为零。只按 Token 消耗筛选的仪表盘会漏掉 MCP 活动。应使用 mcp_server_name、mcp_tool_name 和事件计数进行调用量统计与归因。

延迟字段也需要谨慎解读。当前 AISIX MCP 实现会发起一次覆盖完整请求的上游尝试，因此 upstream_latency_ms 和 downstream_latency_ms 记录相同时长。保留两个独立字段，是为了让事件结构与其他网关流量保持一致；对于其他流量，重试或额外处理可能使二者不同。不要根据当前 MCP 链路不会产生的差值，推断重试开销、故障转移或网关排队时间。

用量事件使用与模型用量相同的已配置导出路径。在 AISIX Cloud 中，它们还会到达控制面的用量接收端。这条共享链路让团队可以在调用方 key 边界关联模型与工具活动，同时不会把 Token 与工具调用的成本模型混为一谈。

使用 Prometheus 构建 MCP 仪表盘和告警

AISIX 通过网关专用的 Prometheus 监听端点公开指标，通常位于 GET /metrics。MCP 样本带有标签，运维人员可以将其与其他协议隔离。

以下两个已记录的指标族可以作为起点：

目标指标与过滤条件
跟踪进行中的 MCP 请求aisix_proxy_in_flight_requests{endpoint="/mcp",inbound_protocol="mcp"}
确认 MCP 用量事件发送aisix_usage_events_emitted_total{handler="mcp",inbound_protocol="mcp"}

指标族会在首次观测后出现。尚未发生 MCP 工具调用的新网关可能暂时没有包含 MCP 标签的时间序列。应先生成一次受控调用，再把时间序列缺失判定为故障。

下面的 PromQL 表达式会显示所有被抓取网关实例上，当前进行中的 MCP 请求总数：

1sum(aisix_proxy_in_flight_requests{endpoint="/mcp",inbound_protocol="mcp"})

下面的表达式会显示五分钟内 MCP 用量事件的发送速率：

1sum(
2  rate(
3    aisix_usage_events_emitted_total{
4      handler="mcp",
5      inbound_protocol="mcp"
6    }[5m]
7  )
8)

应使用 Prometheus 观察网关与导出组件的实时健康状态，再根据用量事件构建更丰富的工具仪表盘。实用的仪表盘可以分为两层。

网关健康面板：

  • 当前进行中的 MCP 请求；
  • 用量事件发送速率；
  • 按部署添加的基础设施标签（例如网关实例或环境）拆分的同类指标；
  • 周边监控栈提供的抓取健康状态和导出组件错误。

用量事件面板：

  • 随时间变化的工具调用尝试总数；
  • 按事件数排名的热门工具与 Server；
  • 按 Server 展示的成功与非成功结果；
  • 按 Server 和工具展示的延迟；
  • 按调用方 key 展示的防护规则阻断调用；
  • 高流量调用方及其相对基线的突变。

不要为没有相应文档的 Prometheus 时间序列虚构 Server 或工具标签。AISIX 用量事件才是 mcp_server_name 和 mcp_tool_name 的受支持来源。把高基数名称保留在事件链路中，还能避免将每个工具与调用方组合转化为不受控制的指标时间序列。

告警应描述可操作的故障模式，而不是模糊的流量变化。实用示例包括：

  • 持续进行中的请求超过网关部署经过测试的容量；
  • 执行受控健康调用时，用量事件发送量降至零；
  • 用量事件查询显示某个 Server 的非成功状态大幅增加；
  • 一个调用方 key 反复出现 guardrail_blocked=true 事件；
  • 某个新调用方成为敏感工具的主要调用来源；
  • 通常响应很快的工具延迟超过其运维目标。

阈值应来自实测流量基线和上游容量。统一的“超过十次调用”告警对搜索工具可能充满噪声，但对破坏性管理工具又可能高得危险。

在不收集载荷的情况下排查 MCP 事件

假设某个运维智能体的操作手册搜索开始失败。排查应从广泛信号逐步收窄到具体请求，而且不需要获取搜索文本本身。

1sequenceDiagram
2    participant Alert as 监控告警
3    participant Metrics as Prometheus
4    participant Events as 用量事件存储
5    participant Logs as 网关与上游日志
6    participant Owner as 平台或安全负责人
7
8    Alert->>Metrics: 确认活跃 MCP 流量和事件发送
9    Metrics-->>Owner: 网关链路健康
10    Owner->>Events: 按 Server、工具、状态和时间过滤
11    Events-->>Owner: 找到调用方 key 和 request_id
12    Owner->>Logs: 使用 request_id 关联且不查询载荷内容
13    Logs-->>Owner: 策略拒绝或上游故障上下文
14    Owner->>Owner: 调整策略、限制、凭证或上游服务

可以采用以下流程：

  1. 确认数据链路。 检查网关是否公开 MCP 指标，并在执行受控调用时确认用量事件计数器持续增加。这样可以区分可观测性故障与工具故障。
  2. 缩小事件范围。 按照 occurred_at、mcp_server_name 和 mcp_tool_name 过滤用量事件，比较成功与非成功状态。
  3. 识别调用方。 使用 api_key_id 判断问题影响一个应用、一个团队，还是该 Server 的所有调用方。
  4. 检查策略证据。 guardrail_blocked=true 可以直接识别内容策略决策。对于限流或预算失败，应通过状态和 request ID 关联网关日志，以及调用方已配置的限制或预算状态。
  5. 检查时间。 使用记录的延迟发现缓慢上游。请记住，当前 MCP 链路只记录一次上游尝试，不要据此诊断没有文档支持的重试循环。
  6. 安全关联。 使用 request_id 关联网关与上游日志。只有当元数据不足时，才能通过明确批准且受访问控制的流程升级到内容捕获。
  7. 实施最小范围修复。 轮换一项上游凭证、调整一项 Server 限制、优化一条防护规则，或修复一个后端。不要为了处理局部问题而关闭整个 MCP 控制层。

该流程也有助于区分策略发布与上游事件。如果某项规则变更后防护规则阻断突然集中出现，很可能需要调优。如果状态变化只发生在一个 Server，而且策略信号不变，则更可能是上游或凭证问题。如果一个 key 的调用量骤增，则可能是智能体循环失控或调用方凭证被盗用。

MCP 可观测性常见问题

AISIX 会在用量事件中存储工具参数或结果吗？

不会。用量事件包含调用方、路由、结果、时间和策略元数据，但不包含工具参数或结果。防护规则可以检查链路中的内容，而无需把内容加入事件。

为什么 MCP 调用的 Token 和成本值为零？

MCP 工具不会在网关处消耗模型 Token。应统计 tools/call 用量事件来衡量工具调用量，不要把 Token 成本仪表盘当作工具调用账本。

如何定位单个工具的故障？

按时间、mcp_server_name 和 mcp_tool_name 过滤事件，再使用 api_key_id 衡量调用方影响范围，并通过 request_id 关联网关与上游日志。Prometheus 用于确认网关和事件链路的实时健康状态，高基数工具诊断则应在用量事件中完成。

将 MCP 作为一等流量类型运维

MCP 可观测性应保留 HTTP 访问日志无法表达的语义：调用方、Server、工具、策略结果与延迟。AISIX 用量事件为每次尝试的工具调用提供这些维度，其中也包括上游前拒绝。Prometheus 指标则显示 MCP 请求是否活跃，以及用量链路是否正在发送事件。

隐私边界同样重要。用量遥测会记录运维团队管理平台所需的信息，但不会把工具参数和结果复制到每条事件中。防护规则检查与内容存储是不同决策，应分别治理。

可以先发送一次受控 MCP 工具调用，验证带标签的指标，通过 request ID 找到对应的用量事件，再基于已记录字段构建仪表盘。随后，根据实测流量和每类工具的风险设置告警。

有关当前遥测契约，请参阅 AISIX MCP 可观测性指南和指标参考。要完整了解本系列，还可以阅读如何将 REST API 转换为 MCP 工具、落实最小权限 MCP 访问，以及使用防护规则和限流保护 MCP 调用。

获取方案