Skip to navigation

Agent Approval plugin

The Agent Approval plugin requires a human approval token on requests that match its conditions, such as a method, a path, or an MCP tool. An agent sends the token in a header, or, on an MCP tools/call, in an approval parameter. Without a valid token, the request is refused. Only agents are asked unless apply_to_humans is on.

A caller is an agent when JWT Auth identified it and its token marks it as an agent.

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. require_for.mcp_tools and the approval parameter apply to MCP tools/call only.
Scope kindsglobal, route, on MCP routes
PhaseRequest

Configuration

require_for.methods
array of strings

Methods that need approval, in any letter case. The console labels this Require methods.

require_for.path_exact
array of strings

Exact paths that need approval.

require_for.path_prefixes
array of strings

Path prefixes that need approval. The console labels this Require path prefixes.

require_for.scopes
array of strings

A caller holding any of these scopes needs approval. The console labels this Require scopes.

require_for.mcp_tools
array of strings

MCP tool name patterns that need approval. A pattern ending in * matches by prefix, and one starting with * matches by suffix.

approval_header
stringDefaults to X-Agent-Approval

The header that carries the token.

validator
stringDefaults to static (on most data planes)

How to check the token. static checks it against static_tokens. A data plane set up with an identity service defaults to a different validator, so always set validator to static and fill in static_tokens. The console labels the blank option “default (iam)”.

static_tokens
object

Maps an approver name to sha256: followed by the full 64-character hexadecimal SHA-256 of that approver’s secret. The gateway checks the stored value only as a prefix, so a shorter or empty value approves other secrets.

apply_to_humans
booleanDefaults to false

Also asks users and callers with no agent identity for approval.

With no require_for condition, nothing needs approval. A request needs approval when any one condition holds.

With the static validator, the token has the form <approver>:<secret>. A missing token gets “human approval required”, and an invalid one gets “approval token rejected”. The token stays on the request and is forwarded to the upstream.

Example

{
"name": "approve-deletes",
"plugin_id": "agent-approval",
"scope": { "kind": "route", "name": "linear-mcp" },
"config": {
"require_for": { "mcp_tools": ["delete_*"] },
"validator": "static",
"static_tokens": {
"alice": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
}
}