Custom Rule Engines

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.

A custom rule engine lets you use an external service as a gateway rule 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, or 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.

​

Adding a rule engine

Open Rule Engines in the left-hand navigation and click Add. You first choose a provider: 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.

​

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 (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). Off by default.
• Headers — static custom headers sent on every call (see 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 <your-token>
• API key — X-Api-Key: <your-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.

​

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 — 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.

​

Using an engine on a gateway rule

Once an engine is registered, it appears in the Detection method dropdown of the rule editor 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.
• 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 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