Skip to main content
API7.ai Logo

Guardrails

AISIX AI Gateway can run guardrails on MCP tool calls before the upstream tool is called and before the tool result returns to the client. A blocked call is rejected with an MCP protocol error and is never sent to the upstream MCP server.

MCP tool calls use the same guardrail chain that governs model traffic. Create guardrails in the shared traffic-control section, then attach them at a scope that can apply to MCP traffic. For shared scope and enforcement-mode behavior, see Guardrail Behavior.

How Guardrails Apply to MCP​

The gateway runs guardrails only on tools/call requests. The MCP handshake and tools/list carry no tool content and are not scanned.

For each tool call, AISIX resolves the guardrail chain once and runs both directions through it:

  • Input: the tool-call arguments are scanned before the call. If a guardrail blocks, AISIX rejects the call and never contacts the upstream server.
  • Output: the tool result is scanned before it returns to the client. If a guardrail blocks, AISIX withholds the result and returns a protocol error instead.

An MCP tool call has no model, so model-scoped guardrails do not apply to MCP. Guardrails scoped to the environment, caller API key, or team do apply. A self-hosted guardrail created through the Admin API applies across the environment; the AISIX managed control plane can additionally scope guardrails to caller API keys or teams.

When no guardrail matches the caller, the tool call runs with no added guardrail latency.

What Gets Scanned​

  • Input: the arguments object of the tools/call request. AISIX feeds the arguments to the same input hook the model path uses.
  • Output: the text content of the tool result. AISIX decodes the result's text content blocks and scans that prose, not the serialized JSON envelope. Envelope field names cannot trigger a false positive, and escaped characters cannot hide blocked content.

A protocol-level error result with no result payload has no tool output to scan and is allowed through.

The gateway inspects MCP tool arguments and results in flight. It does not store them; content capture is a separate surface from guardrail inspection.

Block Response​

When a guardrail blocks a tool call or tool result, AISIX returns HTTP 200 with a JSON-RPC error envelope, not the model path's HTTP 422. MCP clients expect a JSON-RPC response, so the block surfaces as a protocol error the client can handle:

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

The message names the firing guardrail and whether the input arguments or output result was blocked. The gateway records the blocked call as a usage event with its guardrail-blocked flag set.

info

If a tool result cannot be parsed as the expected JSON response, AISIX blocks it rather than returning an unscanned result. A guardrail-attached call never returns tool output that the guardrail could not inspect.

For the full MCP error format and other MCP status behavior, see Headers and Error Codes.

Verify Guardrail Blocking​

Attach a keyword guardrail at the environment scope with a term you can trigger, such as secret. See Built-in Keyword Guardrails for the create command.

Then connect an MCP client with a caller API key that allows a tool, and call that tool with an argument containing the blocked term.

The tool call should return HTTP 200 with a JSON-RPC error envelope whose code is -32600, and the upstream MCP server is never contacted. A call whose arguments and result are both clean returns normally. Switching the guardrail to monitor mode lets the same call through while still recording the match; see Use Monitor Mode.

Managed Control Plane​

In the AISIX managed control plane, create and attach guardrails from the control plane instead of sending Admin API commands directly. To inspect MCP tool calls, use a scope that can apply to non-model traffic, such as the whole environment, caller API key, or team.

Do not use a model-specific scope when the guardrail should inspect MCP traffic. An MCP tool call has no model, so a model-scoped guardrail never runs on it.

Next Steps​

You now understand how guardrails inspect MCP tool arguments and results. Use these guides to create guardrails or observe the blocked calls: