# MCP Tool Gating element

> Field reference for the MCP Tool Gating firewall element: allow/deny gates that match MCP tool names by regex pattern, with an optional OPA condition and a configurable default policy.

MCP Tool Gating is a firewall element that filters which MCP tools a caller can see and call, matched by regular expression over the tool name rather than by an exact tool identifier. Drop it on the response edge coming back from the external target or from a Transit Point on an MCP surface; it is not available on other protocols. Reach for it instead of [per-tool policy bindings](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/mcp-proxy-tool-policies.md) when a rule should cover a whole family of tool names at once, or when whether a rule applies at all should depend on the caller rather than always being on. Per-tool policy bindings remain the right choice when you are binding one distinct policy to one exact, known tool name.

- Reach for a plain regex gate, with no condition, when the tools you want to filter share a naming pattern and the decision does not depend on who is calling.

- Add a Condition when a gate should only be active for some requests, for example only for callers outside a particular organisation. The condition is an OPA policy; an ALLOW result activates the gate, and a deny leaves it inactive.

- Choose “Allowed, unless denied by a gate below” when most tools should stay reachable and you only need to hide a small subset, such as admin or destructive tools.

- Choose “Denied, unless allowed by a gate below” when a Managed Agent should only reach a small, explicit set of tools. Add an Allow gate for each tool or tool family you want to expose.

## Fields

The top-level Default policy sets the baseline for any tool that no gate matches. Each Tool Gate below it is an exception to that baseline. A newly added gate defaults to the effect that carves against the current Default Policy: Deny when tools are allowed by default, Allow when they are denied by default, since that is the effect that actually changes anything.

| Field | What it does | Default |
| Default policy | Sets what happens to a tool that no active gate matches: “Allowed, unless denied by a gate below” or “Denied, unless allowed by a gate below”. | Allowed, unless denied by a gate below |
| Name | A short label for the gate, shown in the gate list and in logs. Purely for your own reference; it has no effect on matching. | — |
| Description | Optional free-text notes shown in the dashboard. Has no runtime effect. | — |
| Condition (OPA policy) | An OPA policy definition that decides whether this gate is active. The gate is active only when the policy evaluates to ALLOW; a deny leaves the gate inactive for that request. Leave it at “Do not use a Policy: always enforce this rule” to make the gate always active. | Always active (no condition) |
| Action | Whether matching tools are denied (“Deny: hide tools matching the regex”) or explicitly allowed (“Allow: permit tools matching the regex”). | Opposite of the surface’s Default Policy |
| Tool name regex patterns | One or more regular expressions matched against tool names. Matching is unanchored, so a pattern matches if it appears anywhere in the name; anchor with ^ and $ for an exact match. A gate needs at least one pattern to have any effect. | None |

The dashboard rejects a save once a single gating configuration exceeds 64 gates, 64 patterns on one gate, or a pattern longer than 512 characters.

### Testing gates before you save

The fullscreen editor includes a Test (dry-run) panel: paste or type sample tool names and run them against the Default Policy and gates you have not yet saved, to preview which gates would match before anything is enforced. The dry-run evaluates regex matching only. It does not evaluate OPA conditions; every conditional gate is treated as active for the purposes of the test, so a gate whose real Condition would leave it inactive can still show as matching in the dry-run result.

## How gates compose

A gate is active when it has no Condition, or its Condition policy evaluates to ALLOW. A Condition that cannot be evaluated, because the policy is missing, disabled, or errors at runtime, fails closed: a Deny gate stays active, but an Allow gate is treated as inactive, so a broken condition can never grant access it would not otherwise have granted.

Given the set of active gates, a tool is allowed when both of these hold:

- No active Deny gate matches it.

- At least one active Allow gate matches it, with the matches of every active Allow gate combining into one allow-list. Or, if no active Allow gate matches, the Default Policy is “Allowed, unless denied by a gate below”.

Deny always overrides Allow for the same tool. Under an allow-by-default policy, Allow gates have no effect of their own since everything not denied is already allowed; only Deny gates change the outcome, as carve-outs from the default. Under a deny-by-default policy, Allow gates build the allow-list, and a Deny gate only changes the outcome where its pattern overlaps an Allow gate’s pattern; a Deny gate with no overlapping Allow gate is redundant, because the tool it targets was already hidden by the default.

## Enforcement

The firewall applies to both the tools/list response, which hides matching tools from discovery, and tools/call requests, which blocks invocation, so a tool hidden from the list cannot be called by name either. A gate dropped on the external target’s response edge applies across the surface; a gate dropped on a Transit Point’s response edge applies only to calls the Managed Agent makes through that Transit Point, independently of the surface-wide gate and of any gate on other Transit Points.

## Relationship to OPA policies

MCP Tool Gating sits in the same Security & Policy palette category as the Policy element, and a gate’s Condition is a real policy definition selected from the same store the Policy element uses, with the same versioning and content-hash tracking described in [OPA policies](/products/affinidi-trust-fabric/agent-gateway/concepts/opa-policies.md#how-policy-definitions-are-versioned-tested-and-evidenced). Beyond that, the two systems diverge:

- The gate logic itself, matching a tool name against a regex pattern and applying the default policy, does not evaluate Rego. Only the optional Condition does.

- A gate hiding or blocking a tool is not recorded as a Policy Decisions entry on the Audit page, and carries none of the version or content-hash evidence a Policy element’s decision does. If you need an audit trail for a tool-access decision, use [per-tool policy bindings](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/mcp-proxy-tool-policies.md) or a Policy element instead, both of which are recorded.

## Related

- [Per-tool policy bindings](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/mcp-proxy-tool-policies.md): the exact-tool-name OPA policy binding mechanism on an MCP Proxy hop. Use it instead of MCP Tool Gating when a policy applies to one known tool name rather than a pattern.

- [Surface reference](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/surface-reference.md): the full canvas element catalogue, including where MCP Tool Gating fits among other surface elements.

- [MCP protocol](/products/affinidi-trust-fabric/agent-gateway/concepts/protocols/mcp.md): conceptual overview of how the gateway handles MCP traffic, including tool-level access control.

- [OPA policies](/products/affinidi-trust-fabric/agent-gateway/concepts/opa-policies.md): the versioned policy definitions store a gate’s Condition selects from.