跳到主要内容

安全护栏

AISIX AI 网关可以在调用上游工具之前，以及工具结果返回客户端之前，对 MCP 工具调用执行安全护栏。被阻断的调用会以 MCP 协议错误返回，并且不会发送到上游 MCP 服务器。

MCP 工具调用使用与模型流量相同的安全护栏链。请在共享的流量控制部分创建安全护栏，然后将其挂载到可以作用于 MCP 流量的作用域。与模型路径共用的作用域和执行模式语义请参见安全护栏行为。

安全护栏如何作用于 MCP​

网关只会对 tools/call 请求执行安全护栏。MCP 握手和 tools/list 不包含工具内容，因此不会被扫描。

对于每个工具调用，AISIX 会解析一次安全护栏链，并在输入和输出两个方向运行：

  • 输入：AISIX 会在调用工具之前扫描工具调用参数。如果安全护栏阻断，请求会被拒绝，AISIX 不会联系上游 MCP 服务器。
  • 输出：AISIX 会在工具结果返回客户端之前扫描结果。如果安全护栏阻断，AISIX 会拦截结果并改为返回协议错误。

MCP 工具调用没有模型，因此模型作用域的安全护栏不会作用于 MCP。环境、调用方 API Key 或团队作用域的安全护栏会生效。通过 Admin API 创建的自托管安全护栏会作用于整个环境；AISIX 托管控制面还可以进一步把安全护栏限定到调用方 API Key 或团队。

当没有匹配的安全护栏时，工具调用不会增加安全护栏带来的额外延迟。

会扫描哪些内容​

  • 输入：tools/call 请求中的参数对象。AISIX 会把参数交给与模型路径相同的输入检查流程。
  • 输出：工具结果中的文本内容。AISIX 会解析结果的 text 内容块并扫描其中的文本，而不是扫描序列化后的 JSON 外层结构。外层字段名不会造成误报，被转义的字符也无法绕过拦截。

没有 result 数据内容的协议级错误结果没有可扫描的工具输出，会被直接放行。

网关只在传输过程中检查 MCP 工具参数或结果，不会存储它们。内容捕获与安全护栏检查是不同的能力边界。

阻断响应​

当安全护栏阻断某个工具调用或工具结果时，AISIX 返回的是 HTTP 200 加 JSON-RPC 错误封装，而不是模型路径中的 HTTP 422。MCP 客户端期望收到 JSON-RPC 响应，因此阻断会以客户端可处理的协议错误呈现：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "tool call blocked by content policy (guardrail 'block-secrets')"
  }
}

错误信息会标明触发的安全护栏，以及被阻断的是输入参数还是输出结果。网关会把被阻断的调用记录为用量事件，并设置安全护栏阻断标记。

信息

如果工具结果无法按预期 JSON 响应解析，AISIX 会阻断该结果，而不是返回未经过扫描的内容。只要调用挂载了安全护栏，就不会返回安全护栏无法检查的工具输出。

完整 MCP 错误格式和其他 MCP 状态行为请参见响应头与错误码。

验证安全护栏阻断​

在环境作用域挂载一个关键词安全护栏，并设置一个容易触发的词，例如阻断 secret。创建命令请参见内置关键词安全护栏。

然后使用允许访问某个工具的调用方 API Key 连接 MCP 客户端，在工具参数中包含被阻断词并调用该工具。

工具调用应返回 HTTP 200 和 JSON-RPC error 封装（code 为 -32600），上游 MCP 服务器不会收到请求。参数和结果都干净的调用会正常返回。把安全护栏切换为监控模式后，同样的调用会被放行，但仍会记录命中信息；详见使用监控模式。

托管控制面​

在 AISIX 托管控制面中，请通过控制面创建和挂载安全护栏，而不是直接发送 Admin API 命令。要检查 MCP 工具调用，请使用可以作用于非模型流量的作用域，例如整个环境、调用方 API Key 或团队。

当安全护栏需要检查 MCP 流量时，不要使用模型专属作用域。MCP 工具调用没有模型，因此模型作用域安全护栏不会运行。

下一步​

你现在已经了解安全护栏如何检查 MCP 工具参数和工具结果。使用下面的指南创建安全护栏，或观察被阻断的调用：