Skip to navigation

Agent Scope Gate plugin

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

ProtocolsThe 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 kindsglobal, route, on MCP routes
PhaseRequest

Configuration

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

FieldTypeDefaultDescription
required_scopesarray of stringsNoneScopes the caller must hold. The console labels this Required scopes.
scope_matchstringallall needs every scope. any needs one of them. The console labels this Scope match.
allow_principal_typesarray of stringsAnyThe principal types allowed: agent (or bot) and user (or human).
require_consumer_groupstringNoneA consumer group that the caller’s token must name, as the consumer group or in a consumer_group, consumer_groups, or groups claim.
methodsobjectNoneMaps 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_scopesobjectNoneMaps an MCP tool name, as the upstream names it, to the scopes needed to call it.
tool_scope_matchstringallall or any, for tool_scopes.
apply_to_humansbooleanfalseAlso 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

{
"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"] }
}
}