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

# Agent Scope Gate plugin

> Reference for the Agent Scope Gate plugin, which requires agents to hold scopes, a principal type, or a consumer group.

The Agent Scope Gate plugin checks an agent's identity before it lets a request through. It can require scopes, a principal type, or a consumer group, and different scopes per HTTP method or per MCP tool. When an agent lists MCP tools, the plugin leaves out the tools whose scopes the agent doesn't hold.

A caller is an agent when [JWT Auth](/reference/plugins/jwt-auth) or Postman API key auth identified it and the identity's kind is agent. Users, and callers identified by Key Auth, pass untouched unless `apply_to_humans` is on.

## Where it runs

|             |                                                                                                                                                                                                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Protocols   | The console offers it for MCP routes. The gateway itself runs it on any protocol, so a `global` instance also applies to HTTP and LLM routes. `methods` applies to every protocol except MCP. `tool_scopes` applies to MCP `tools/call`, and filters `tools/list` and Tool Search results. |
| Scope kinds | `global`, `route`, on MCP routes                                                                                                                                                                                                                                                           |
| Phase       | Request                                                                                                                                                                                                                                                                                    |

## Configuration

If you set none of `required_scopes`, `require_consumer_group`, `allow_principal_types`, `methods`, or `tool_scopes`, the plugin checks nothing.

| Field                    | Type             | Default | Description                                                                                                                                                          |
| ------------------------ | ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `required_scopes`        | array of strings | None    | Scopes the caller must hold. The console labels this **Required scopes**.                                                                                            |
| `scope_match`            | string           | `all`   | `all` needs every scope. `any` needs one of them. The console labels this **Scope match**.                                                                           |
| `allow_principal_types`  | array of strings | Any     | The principal types allowed: `agent` (or `bot`) and `user` (or `human`).                                                                                             |
| `require_consumer_group` | string           | None    | A consumer group that the caller's token must name, as the consumer group or in a `consumer_group`, `consumer_groups`, or `groups` claim.                            |
| `methods`                | object           | None    | Maps an HTTP method to its own `required_scopes` and optional `scope_match`, which replace the top-level values for that method. A method with no scopes needs none. |
| `tool_scopes`            | object           | None    | Maps an MCP tool name, as the upstream names it, to the scopes needed to call it.                                                                                    |
| `tool_scope_match`       | string           | `all`   | `all` or `any`, for `tool_scopes`.                                                                                                                                   |
| `apply_to_humans`        | boolean          | `false` | Also checks users and callers with no agent identity. A caller with no agent identity is then refused.                                                               |

A refused request gets `403` with `{"error":"forbidden","reason":"..."}`. On MCP routes, it gets HTTP `200` with JSON-RPC error `-32002`. The upstream isn't called.

## Example

```json
{
  "name": "mcp-scopes",
  "plugin_id": "agent-scope-gate",
  "scope": { "kind": "route", "name": "linear-mcp" },
  "config": {
    "required_scopes": ["workspace:read"],
    "tool_scopes": { "delete_issue": ["workspace:admin"] }
  }
}
```

## Related guides

* [Authenticate requests with JWT Auth](/configure/authentication/jwt-auth#limit-mcp-tools-with-claims)