Guardrails

AISIX AI Gateway runs guardrails on MCP tool calls in both directions: on the tool-call arguments before the call (input), and on the tool result before it returns to the client (output). MCP tool calls use the same guardrail chain that governs model traffic, so a guardrail you attach for content policy also inspects agent tool traffic. A blocked call is rejected with an MCP protocol error and is never sent to the upstream MCP server.

This page covers how guardrails apply on the MCP path. To create a guardrail and choose its enforcement mode, see Built-in Keyword Guardrails; for provider-backed guardrails, see the provider pages under Add Traffic Controls. For scope and enforcement-mode semantics shared with the model path, 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 never apply to MCP. Guardrails scoped to the environment, the caller API key, or the team do apply. This follows the shared scope-matching rules in Guardrail Behavior: a self-hosted guardrail created through the Admin API applies across the environment; AISIX Cloud can additionally scope guardrails to caller API keys or teams. When no guardrail matches the caller, the tool call runs with no added 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, so envelope field names cannot trigger a false positive and escaped characters cannot hide blocked content. A protocol-level error result (an MCP error with no result payload) has no tool output to scan and is allowed through.

The gateway inspects this content in flight. It does not store MCP tool arguments or results — 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 (tool call) or the output result (tool result) was blocked. The gateway records the blocked call as a usage event with its guardrail-blocked flag set, so blocks are visible in telemetry.

Fail-closed output

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.

Verification

1. Attach a keyword guardrail at the environment scope with a term you can trigger — for example, block the word secret. See Built-in Keyword Guardrails for the create command.
2. Connect an MCP client with a caller API key that allows a tool, then call that tool with an argument containing the blocked term.

Expected result: the tool call returns HTTP 200 with a JSON-RPC error envelope (code -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.

Attach Guardrails to MCP on AISIX Cloud

On AISIX Cloud, you create and attach guardrails from the dashboard instead of the Admin API:

1. Open the environment and go to Guardrails, then create a guardrail.
2. Set its scope to Whole environment. This checks every model request and every MCP tool call in the environment.
3. Do not use the Specific models scope for MCP tool calls: an MCP tool call has no model, so a model-scoped guardrail never runs on it.

Any caller API key in that environment then has its MCP tool arguments and results inspected. See AISIX Cloud.

Next Steps

• Built-in Keyword Guardrails — create a guardrail and choose its enforcement mode.
• Guardrail Behavior — scope matching, enforcement modes, and remote-guardrail failure handling.
• Observability — see blocked tool calls in usage events and metrics.
• Rate Limits and Budgets — throttle and cap MCP tool calls on the same caller API key.