> ## 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.
# Custom Rule Engines
> How to add and manage custom rule engines in MCP Manager: the Rule Engines section, provider choices, endpoint/method/header configuration, HTTPS-only and private-IP rejection, header forwarding, IP allowlisting, testing, and deletion rules.
A **custom rule engine** lets you use an external service as a [gateway rule](/features/gateway-rules/overview) detection method in MCP Manager. Instead of matching patterns or running Presidio in-process, the gateway calls out to a webhook — your own service, an [AWS Bedrock guardrail](/features/amazon-bedrock), or [Lakera Guard](/features/lakera-guard) — and that service decides whether to pass, modify, or block the message. You register engines once in the **Rule Engines** section, then select them as a detection method on any gateway rule.
MCP Manager does **not** meter or charge per call for custom rule engines. As long as your plan includes custom rule engines, the calls the gateway makes to an engine are not metered or billed per call by MCP Manager. Any usage cost is billed by the engine's own provider — for example [AWS](/features/amazon-bedrock) or [Lakera](/features/lakera-guard) — under their pricing; an engine you run yourself carries no such per-call charge.
The **Rule Engines** section, and the ability to add, edit, or remove engines, are controlled by the **Manage integrations** capability ("Configure, edit, and remove integrations such as rule engines, including custom providers and built-in engines"). If you don't see **Rule Engines** in your left-hand navigation, your role doesn't have it. Capabilities are assigned per role and are fully configurable, including on custom roles, so access depends on the capability granted to your role, not on any fixed role name.
## Adding a rule engine
Open **Rule Engines** in the left-hand navigation and click **Add**. You first choose a **provider**:
| Provider | Use it when | Setup guide |
| -------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Custom** | You run your own webhook that speaks MCP Manager's rule-engine contract. | [Building a Custom Rule Engine](/advanced/building-a-custom-rule-engine) |
| **AWS Bedrock Guardrails** | You want to apply an Amazon Bedrock guardrail; MCP Manager builds the request for you. | [Amazon Bedrock](/features/amazon-bedrock) |
| **Lakera Guard** | You want to use Lakera's hosted guardrail. | [Lakera Guard](/features/lakera-guard) |
All three providers share a common set of fields; the provider you pick determines which fields are editable and which MCP Manager fills in for you.
Running the **Custom** provider? See the full webhook contract — the request envelope, the four response verdicts, TypeScript types, and a working Express example.
## Configuration fields
* **Name** — a label for the engine (up to 120 characters). It appears in the detection-method dropdown and alongside the rule wherever the engine is applied.
* **Description** — a longer description, shown next to the rule when the engine is applied to a gateway.
* **Endpoint URL** — the webhook MCP Manager calls (up to 256 characters). For the **Custom** provider you type this directly; for **AWS Bedrock** it is built automatically from the guardrail ARN and version; for **Lakera Guard** it is fixed at `https://api.lakera.ai/v2/guard`.
* **HTTP method** — the verb MCP Manager uses: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Defaults to **POST**; the Bedrock and Lakera templates lock it to POST.
* **Default direction** — the [detection hook](/features/gateway-rules/overview#detection-hook-when-a-rule-fires) (request, response, or both) this engine pre-selects when you add a rule that uses it. It is a recommendation, not a lock — you can override it per rule.
* **Forward inbound server headers** — whether to pass the inbound runtime headers to your engine (see [Forwarding runtime headers](#forwarding-runtime-headers)). Off by default.
* **Headers** — static custom headers sent on every call (see [Authenticating your engine](#authenticating-your-engine)).
## Only HTTPS, public endpoints
For security, MCP Manager requires every rule-engine URL to use **HTTPS**, and it rejects URLs that resolve to **private, loopback, link-local, or carrier-grade-NAT IP ranges**. Your engine must be reachable on the public internet. A non-HTTPS URL is rejected with *"Webhook URL must use https\://"*, and a private address with *"Webhook URL resolves to a non-public IP …, which is not permitted. Customer-supplied rule engine webhooks must be reachable on a public network."* This guard prevents the gateway from being used to reach or scan internal infrastructure.
## Authenticating your engine
Don't expose a rule engine on the public internet without locking it down. Anything you add under **Headers** is sent on every request and stored **encrypted at rest** until call time. Common patterns:
* **Bearer token** — `Authorization: Bearer `
* **API key** — `X-Api-Key: `, or whatever header your service expects
## Forwarding runtime headers
Switching on **Forward inbound server headers** copies the headers from the inbound connection — including the calling user's identity and any OAuth tokens — through to your engine. This is what makes identity-aware guardrails possible.
For example, to forbid access to files inside a particular Google Drive folder, your engine can read the file IDs out of the message and then call the Google Drive API *as the requesting user* to resolve each file's parent folder — a lookup that's only possible with the user's forwarded identity.
MCP Manager ships this exact guardrail for you as the [Google Drive Folder Blocker](/features/gateway-rules/google-drive-folder-blocker) — a managed engine that protects Drive folders by walking the folder hierarchy under the requesting user's identity. Enable it without building anything yourself.
Forwarding runtime headers hands your engine custody of the inbound connection's **secure headers**, including identity and access tokens. Only forward headers to an engine you trust and control, and make sure it is [authenticated](#authenticating-your-engine) and ideally [IP-allowlisted](#defense-in-depth-allowlist-mcp-managers-ip).
## Defense in depth: allowlist MCP Manager's IP
Beyond header-based authentication, a sophisticated engine can accept connections **only from MCP Manager** by allowlisting MCP Manager's static outbound IP address. Find it at [Security → IP addresses](https://app.mcpmanager.ai/settings/security/ip-addresses) — a single static IP you can add to your firewall or service allowlist.
## Testing an engine
Every rule engine has a **Test** action. It opens a modal where you enter sample text (up to 500 characters) and previews how the engine would respond — its verdict and how long the call took — without attaching the engine to a gateway.
The test runs **outside a live gateway session**, so it can't supply [forwarded runtime headers](#forwarding-runtime-headers). An engine that depends on forwarded identity headers won't behave the same way under test as it does in production — there's no inbound connection to forward from.
## Using an engine on a gateway rule
Once an engine is registered, it appears in the **Detection method** dropdown of the [rule editor](/features/gateway-rules/overview#add-a-new-rule) on every gateway. A rule that uses a custom engine differs from a built-in rule in two ways:
* **No action picker.** The engine's response — `pass`, `modify`, `block`, or `error` — determines what happens, so there is no action to choose. See the [webhook contract](/advanced/building-a-custom-rule-engine).
* **Failure mode defaults to Block.** If the engine is unreachable, too slow, returns invalid data, or signals an error, the message is blocked unless you set the rule's [failure mode](/features/gateway-rules/overview#failure-mode-what-happens-when-a-detection-method-fails) to **Allow**.
## Deleting a rule engine
You can't delete a rule engine while it's still used by one or more gateway rules. To remove it, first delete every rule that references it — on each gateway's **Rules** tab — then return to **Rule Engines** and delete the engine.
## Further reading
The full webhook contract for the Custom provider — envelope, verdicts, and a working example.
Detection methods, hooks, failure modes, actions, and rule ordering.
The AWS Bedrock template for a managed guardrail engine.
The Lakera Guard template for security-first detection.
A hands-on lesson: write a webhook, register it, and watch its verdict in the logs.