> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Control and transform gateway traffic with plugins

Every request that passes through Fabric Gateway runs through a *policy chain* — an ordered set of plugins that can inspect, allow, deny, or rewrite traffic at different points in the request lifecycle. You can use built-in plugins to add authentication, rate limiting, logging, and header or body transforms to any route without writing or deploying custom code.

Learn how the plugin catalog works and how to create a plugin instance that attaches a plugin to your traffic.

## Understanding the plugin catalog

The **Plugin catalog** lists every built-in plugin available in your tenant. Fabric Gateway ships with 26 plugins, and the catalog is read-only. It shows you what each plugin can do, not your configuration of it.

Each plugin in the catalog has the following properties:

| Property         | Description                                                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Phases**       | The lifecycle stages the plugin can run in: `request`, `response`, `complete`, or `error`.                                                                          |
| **Auth-capable** | Whether the plugin can establish caller identity.                                                                                                                   |
| **Fail default** | What happens if the plugin itself fails: `fail-closed` (block the request) or `fail-open` (let it through).                                                         |
| **Reads**        | The request and response fields the plugin can inspect, such as `request.headers`, `identity.consumer`, or `mcp.tool`.                                              |
| **Mutates**      | The fields the plugin is allowed to change. Most plugins mutate nothing.                                                                                            |
| **Scope**        | Where the plugin can be attached — for example, some plugins only work when scoped to a consumer, while others can be scoped globally, to a service, or to a route. |

The catalog includes:

* Authentication & credentials — JWT Auth, Key Auth, PMAK Auth, and Auth Broker
* Access control & rate limiting — Access Control, Deny All, Killswitch, Rate Limit, and LLM Rate Limit
* Agent & tool governance — Agent Approval, Agent Audit, Agent Scope Gate, Agent Static Deny, and Tool Search
* LLM routing & providers — LLM Router and Provider Passthrough
* Observability & metering — Access Log, LLM Logger, LLM Metering, LLM Stream Collector, and Token Counter
* Transformation & data protection — Transformer, Validator, PII Redaction, and Transponder LLM

The **Transformer** and **Validator** plugins are the most versatile in the catalog. Both can run in the request and response phases, can read nearly every available field, and can mutate headers, query parameters, body, and cookies. They can do so only when scoped globally, to a service or to a route.

## Add a plugin instance

A plugin in the catalog doesn't do anything on its own. To apply it to traffic, create a *plugin instance* that attaches the plugin to a scope and configures it.

To add a plugin instance, do the following:

1. In the sidebar, select **Plugin instances** under **Policies**.
2. Click **New instance**.
3. Select **Plugin**, then choose a plugin from the catalog, such as **transformer** or **rate-limit**.
4. Enter a **Name** for the instance. Names must be unique within your tenant, and you can't change the name after creation.
5. Select a **Scope kind**, such as **global** or **route**. If you choose a scope narrower than global, also select a **Scope name**, such as a specific route.
6. Under **Configuration**, configure the plugin using its dedicated form, or click **Edit as JSON** to provide raw configuration.
7. Optionally, add **Match conditions** to limit when the instance runs:
   * **Path prefix**
   * **Methods**
   * **Only run for consumer**
   * **Only run for consumer group**
8. Under **Status**, make sure **Enabled** is selected. Disabled instances are saved but skipped at request time, so you can stage a configuration without activating it.
9. Click **Save**.

### Example: Rewrite a header with the transformer plugin

The following example adds a transform that sets an `X-Api-Key` header on every matching request.

1. Add a plugin instance and select **transformer** as the plugin.
2. Under **Transforms**, set:
   * **Phase**: `Request`
   * **Operation**: `set`
   * **Target**: `Header`
   * **Name**: `X-Api-Key`
   * **Value**: `prod`
3. Review the **Compiled policy (Rego)** panel. This is a read-only preview of the OPA policy that the control plane compiles from your transform and ships down to the data plane's sidecar.
4. Click **Save**.

### Example: rate limit an MCP route

The following example limits traffic to a specific MCP route.

1. Add a plugin instance and select **rate-limit** as the plugin.
2. Set **Scope kind** to **route** and **Scope name** to the route you want to limit, for example `linear-mcp`.
3. Under **Configuration**, set **Count by** to one of the following:
   * **Consumer** — One counter per authenticated caller. Requires auth on the route.
   * **Credential** — One counter per API key. Only populated when key-auth is in use.
   * **Global** — One counter for every request. The only option that works without auth.
4. Set **Window (seconds)**. This defaults to `60` if left unset.
5. Click **Save**.

To see how a plugin's execution appears in request traces, see [Monitor gateway traffic with analytics and traces](/fabric/observability/).