跳到主要内容

安全护栏

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

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

安全护栏如何作用于 MCP​

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

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

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

MCP 工具调用没有模型，因此模型作用域的安全护栏不会作用于 MCP。在 AISIX Cloud 中，环境、指定 MCP 服务器、调用方 API Key 或团队作用域的安全护栏会生效。在开源 AISIX 网关中，资源文件里每个已启用的安全护栏都会作用于所有请求，包括 MCP 工具调用。

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

会扫描哪些内容​

  • 输入：tools/call 请求中的参数对象。AISIX 会把参数交给与模型路径相同的输入检查流程。
  • 输出：工具结果中的文本内容。AISIX 会解析结果的 text 内容块并扫描其中的文本，而不是扫描序列化后的 JSON 外层结构。外层字段名不会造成误报，被转义的字符也无法绕过拦截。
  • 输出：结果中 structuredContent 里的取值。返回结构化输出的工具会把该字段与 content 一起发送给客户端，而且它不一定会被同时写入文本块，因此 AISIX 会遍历该字段并扫描其中的字符串值。字段名不会被扫描——它们属于工具的输出结构定义，而不是数据本身。

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

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

阻断响应​

当安全护栏阻断某个工具调用或工具结果时，AISIX 返回的是 HTTP 200 加标记了 isError 的工具结果，而不是模型路径中的 HTTP 422：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "tool call blocked by content policy (guardrail 'block-secrets')" }],
    "isError": true
  }
}

MCP 区分两类失败：请求本身不合法属于 JSON-RPC 协议错误，而调用没有成功则通过结果中的 isError 表达。策略拒绝属于后者——请求格式是合法的，因此拒绝会作为工具输出返回给调用方 Agent，让它能够读取并据此调整，而不是被当作传输层故障。

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

信息

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

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

将安全护栏限定到单个 MCP 服务器​

使用 mcp_server 作用域并指定某个已注册服务器的 ID 挂载安全护栏，即可只检查路由到该服务器的工具调用。两个方向依然都会生效：发往该服务器的每次调用参数，以及它返回的结果。

对 MCP 流量来说，这是把安全护栏收窄到小于整个环境的唯一方式。模型作用域做不到这一点，因为工具调用不会解析出模型；没有该作用域时，只针对某个敏感服务器的规则就不得不作用于环境内的所有 MCP 工具调用。

该服务器必须已在你挂载所在的环境中开放。AISIX 会拒绝指向未在本环境开放的服务器的挂载，因为本环境的工具调用永远不会路由到它。要覆盖多个服务器时，每个服务器各挂载一条；安全护栏在单次请求中仍然只运行一次。

验证安全护栏阻断​

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

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

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

AISIX Cloud 控制面​

在 AISIX Cloud 中，请通过控制面创建和挂载安全护栏，而不是在资源文件中声明。要检查 MCP 工具调用，请使用可以作用于非模型流量的作用域：整个环境、指定 MCP 服务器、调用方 API Key 或团队。

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

早于 MCP 服务器作用域的网关不认识该作用域，会丢弃这条挂载记录。当一个安全护栏在该网关上没有任何可识别的挂载记录时，它会退回为对整个环境生效——规则作用的流量范围会被放大而不是收窄。只要环境中还有数据面运行在这类版本上，AISIX 会在保存时给出提示；请先升级这些网关，再依赖更窄的作用域。

下一步​

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