> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpmanager.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Gateway Rules Overview
> How gateway rules work in MCP Manager: the per-gateway Rules tab, the detection methods (regex, Microsoft Presidio, custom engines), detection hooks, failure modes, actions, alerts, rule ordering, and how rule activity appears in logs.
Every tool call that passes through an MCP Manager gateway can be inspected and acted on before it continues. **Gateway rules** are the content-level policies that do this. Each rule is attached to one gateway and runs only on the tool traffic flowing through that gateway, so different gateways can enforce different policy — one way to scope rules per client, team, or tenant. When a rule matches it can **block** the message, **modify** its contents, or let it through while raising an **alert**. You create and manage rules on a gateway's **Rules** tab: open a gateway from [Gateways](https://app.mcpmanager.ai/settings/gateways) in the left-hand navigation and select **Rules**.
A rule is built from two halves: a **detection method** (what to look for) and what to do about it (an **action** — or, for custom engines, the engine's own verdict). MCP Manager ships two built-in detection methods, [regular expressions](/features/gateway-rules/regex) and [Microsoft Presidio](/features/gateway-rules/presidio), and lets you plug in your own [custom rule engines](/features/gateway-rules/custom-rules-engines) — including the [AWS Bedrock Guardrails](/features/amazon-bedrock) and [Lakera Guard](/features/lakera-guard) templates, or [build your own](/advanced/building-a-custom-rule-engine).
Gateway rules currently apply to **tools only** — tool calls and tool results (the MCP `tools/call` method). They do **not** run on prompts (`prompts/get`) or resources (`resources/read`). A rule you create will never see, block, or modify a prompt or resource message.
If you don't see a **Rules** tab on a gateway, your role doesn't have the capability to manage that gateway. Building [custom rule engines](/features/gateway-rules/custom-rules-engines) is separately controlled by the **Manage integrations** capability — if the **Rule Engines** section is missing from your left-hand navigation, your role lacks it. Capabilities are assigned per role and are fully configurable, including on custom roles, so access depends on the capabilities granted to your role, not on any fixed role name.
## Where gateway rules run in a tool call
A gateway rule fires at one of two points in a tool call's round trip — on the **request** leg (the client's `tools/call` heading to the MCP server) or the **response** leg (the server's result heading back to the client). The diagram shows both hook points:
```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Lato, sans-serif','actorBkg':'#aed8ff','actorBorder':'#0b4880','actorTextColor':'#062b4c','signalColor':'#6a6b76','signalTextColor':'#12141d','noteBkgColor':'#fff8e4','noteBorderColor':'#ffa535','noteTextColor':'#12141d'}}}%%
sequenceDiagram
participant Client as 🤖 MCP Client
participant Gateway as 🛡️ MCP Gateway
participant Server as 🖥️ MCP Server
Client->>Gateway: tools/call request
Note over Gateway: Request-hook rules run
Gateway->>Server: request (unless blocked)
Server->>Gateway: tool result
Note over Gateway: Response-hook rules run
Gateway->>Client: response (unless blocked)
```
On the request leg, a rule scans the tool's arguments (`params.arguments`) and can stop the call before it ever reaches the server. On the response leg, a rule scans the tool's result and can stop or rewrite it before it reaches the client. A rule that **blocks** a request means the call never reaches the server; a rule that **blocks** a response means the result never reaches the client.
## The detection methods
The **Detection method** dropdown in the rule editor is populated with both built-in engines and every custom rule engine your workspace has registered:
| Detection method | What it does | Where to read more |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Regular expression** | Matches one or more JavaScript regex patterns against the message text. Built in. | [Regex](/features/gateway-rules/regex) |
| **Microsoft Presidio** | Detects PII (credit cards, SSNs, emails, names, and more) using Microsoft's open-source engine. Built in; available as an add-on. | [Microsoft Presidio](/features/gateway-rules/presidio) |
| **A custom rule engine** | Calls an external webhook you configure under **Rule Engines** — your own service, an AWS Bedrock guardrail, or Lakera Guard. | [Custom rule engines](/features/gateway-rules/custom-rules-engines) |
The two built-in methods are always offered. Below them, the dropdown lists every engine registered in the **Rule Engines** section, so anything you add there becomes selectable as a detection method on any gateway rule.
## Choosing a detection method
The three methods aren't ranked — they're suited to different kinds of data, and most mature setups use more than one. Match the method to what you're trying to catch:
| Choose | When you're matching | Because |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Regular expression** | **Structured** values with a predictable shape — credit-card and Social Security numbers, national IDs, `AKIA…`-style keys, known prompt-injection strings. | Runs in-process, so it's the fastest option, has **no failure mode** to reason about, and supports all five actions (block, redact, replace, mask, hash). |
| **Microsoft Presidio** | **Unstructured, contextual** PII — people's names, emails, phone numbers, locations — where a fixed pattern can't capture the variation. | Model-driven detection reads surrounding context. It's a managed add-on you don't host, tuned with entity types and a confidence threshold. |
| **A custom rule engine** | **Nuanced or domain-specific policy** — jailbreak and prompt-injection intent, toxicity, field-level JSON redaction, or anything you want a model or your own service to judge. | Delegates the decision to [AWS Bedrock](/features/amazon-bedrock), [Lakera Guard](/features/lakera-guard), or [your own webhook](/advanced/building-a-custom-rule-engine) — at the cost of an external round-trip per call. |
A few rules of thumb:
* **Start with regex for anything that has a fixed shape.** It's free in latency terms and deterministic, so structured secrets and IDs are best caught here.
* **Reach for Presidio when the value is a human artifact** — a name or address won't yield to a regex. Tune it against your own traffic; see [Microsoft Presidio](/features/gateway-rules/presidio).
* **Bring a custom engine when the judgment is hard** — intent, context, or policy a pattern can't express. These add the latency of an external call and are bounded by a 30-second timeout and a [failure mode](#failure-mode-what-happens-when-a-detection-method-fails).
* **Layer them.** The methods compose: a regex rule that **blocks** prompt injection placed *first*, then a Presidio rule that **replaces** PII as a safety net, then a custom engine for nuanced policy. Because [rule order](#rule-order-and-the-enable-toggle) matters, put your most decisive rules at the top.
For PII specifically, [PII Filtering](/features/pii-filtering) walks through this decision in the context of keeping customer data out of the model.
## Add a new rule
New to rules? [Add your first gateway rule](/tutorials/first-gateway-rule) walks through this in a safe, non-blocking configuration.
From [Gateways](https://app.mcpmanager.ai/settings/gateways), select the gateway you want to protect and open its **Rules** tab. Click **Add new rule** to open the rule editor.
Enter a **Rule name** — a short, descriptive label such as `Block prompt injection` or `Redact SSNs`. The name identifies the rule in the rules list, in your [logs](/features/viewing-logs), and in any [alerts](/features/alerts) it raises.
Pick **Regular expression**, **Microsoft Presidio**, or one of your custom rule engines from the **Detection method** dropdown. The fields below the dropdown change to match the method you chose.
Set whether the rule fires on the **request**, the **response**, or **both** directions. See [Detection hook](#detection-hook-when-a-rule-fires).
Fill in the method-specific settings — patterns for regex; entity types, confidence, and failure mode for Presidio; failure mode for a custom engine — and, for the built-in methods, choose an **Action**. Custom engines have no action picker; the engine's response carries the action.
Toggle **Alerts** on if you want to be notified whenever the rule acts, then save. The rule appears in the rules list, enabled and ready.
## Detection hook: when a rule fires
The **Detection hook** controls which leg of the tool call a rule runs on:
* **Request** — the rule fires before the `tools/call` reaches the MCP server, scanning the tool's arguments. Use this to stop a call from ever being made.
* **Response** — the rule fires after the server returns its result, scanning the result before it reaches the client. This is the default and the most common choice.
* **Both** — a convenience that, on save, **materializes a paired rule per direction**: one request rule and one response rule, each independently sortable, editable, and toggleable. There is no single "both" rule at runtime — you end up with two rules. When editing an existing rule you can only set a single direction; to cover both, add a second rule.
A custom rule engine can advertise a preferred direction, which pre-selects this picker when you choose that engine — but you can always override it.
## Failure mode: what happens when a detection method fails
Some detection methods call an external system that can fail — Microsoft Presidio, an AWS Bedrock guardrail, Lakera Guard, or your own endpoint. "Fail" means the service is **unreachable**, **too slow**, returns an **invalid response**, or otherwise signals an **error**. For these methods the rule has a **Failure mode** that decides what happens in that case:
* **Block** — a failure blocks the message. A failed request never reaches the server; a failed response never reaches the client. This is the **default for custom rule engines**, so a misconfigured or unavailable engine fails closed rather than silently leaking data.
* **Allow** — a failure lets the original message through unchanged. This is the **default for Microsoft Presidio rules**.
Regular-expression rules run in-process and synchronously, so they have **no failure mode** — there is no external call to fail.
## Actions: what a matching rule does
For the built-in detection methods you choose an **Action** that applies when the rule matches. Custom rule engines do not show an action picker — their webhook response (`pass`, `modify`, `block`, or `error`) determines the outcome.
| Action | Effect | Available for |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
| **Block** | Blocks the message entirely. A blocked tool call never reaches the server; a blocked response never reaches the client. | Regex, Microsoft Presidio |
| **Redact** | Removes the matched text entirely, leaving nothing in its place. | Regex |
| **Replace** | Substitutes the matched text with a placeholder. Regex rules use the constant ``; Microsoft Presidio tags each detected entity by type, such as `` or ``. | Regex, Microsoft Presidio |
| **Mask** | Replaces each character of the match with an asterisk, preserving length (a 16-character value becomes `****************`). | Regex |
| **Hash** | Replaces the match with a truncated SHA-256 hash of the form `` (16 hex characters), letting you correlate repeats without exposing the value. | Regex |
Regular-expression rules support all five actions; Microsoft Presidio rules support **Block** and **Replace** only. For the modification actions (redact, replace, mask, hash), the message continues to the next enabled rule after being rewritten; a **Block** action stops rule processing immediately.
## Alerts
Every rule has an independent **Alerts** toggle. When it's on, MCP Manager raises a real-time alert each time the rule **acts** — whether the action was block, a modification, or a custom engine's verdict — and the alert appears in the [Alerts](/features/alerts) section in the left-hand navigation. You can leave a rule on a non-destructive action (say, **Replace**) and still be alerted every time it fires, which is a good way to roll a rule out safely before switching it to **Block**.
## Rule order and the enable toggle
Rules are listed in the order they run, with a number in the leftmost column. **Hover the number, grab the gripper, and drag** to reorder. Ordering is compared **within a detection hook**: all request-hook rules run in their relative order, and all response-hook rules run in their relative order, independently of each other.
Order matters because a **Block** action stops processing immediately — no later rule runs on that message — while modification actions **chain**, each operating on the text the previous rule already modified. Put your most decisive rules (such as prompt-injection blocking) first.
Each rule also has an **Enabled** toggle. Flipping it takes effect almost immediately, so you can turn a rule off to investigate a false positive and back on without deleting and re-creating it.
## How rule activity appears in your logs
Every time a rule runs it is recorded in your [logs](/features/viewing-logs) — not only when it blocks. Rule-engine activity populates three log columns:
* **`rule_engine_id`** — which engine acted.
* **`rule_engine_type`** — how it classified the message: `pass`, `modify`, or `block`.
* **`rule_engine_comment`** — any comment the engine returned (for a custom engine, the `comment` field of its response).
Alongside these, a blocked message is logged with the type `policy_enforced_abort` and a modified message with `policy_enforced_mutation`, so you can tell from the log type alone whether a rule **blocked**, **modified**, or **allowed** a given message. Block entries also record the specific detection that triggered them — for example the Presidio entity or regex pattern that matched — not just the rule name. See [Viewing Logs](/features/viewing-logs) for the full column reference, and [Alerts](/features/alerts) for the higher-level event feed.
A rule changes what the MCP **client** receives — it is not a control over what gets written to the audit log. The original client request is logged on the inbound leg **before** any request-side rule runs, so a redaction or masking rule on the request never keeps the original out of your logs. On the response leg, a modifying or blocking rule is recorded as the modified or blocked content. Either way, the rule's activity is logged rather than hidden: by default a redaction rule produces an audit record, it does not scrub one. If you need sensitive payloads kept out of the stored log entirely, that can be configured for your workspace on request — discuss it with your MCP Manager contact. To see exactly what each leg stores, see [Audit & Observability](/security/audit-and-observability#what-every-call-records).
## Further reading
Pattern-matching rules for structured secrets and IDs, with all five actions.
Context-aware PII detection, run as a managed add-on.
Plug in AWS Bedrock, Lakera Guard, or your own webhook.
Using rules to keep customer PII out of the model.