MCP Tool Approvals

Tool approval policies add human-in-the-loop control for sensitive MCP tools. When an agent or user calls a gated tool through the MCP Gateway, the call is held, an approval request is created and designated approvers are notified. After a human approves, calls to that tool succeed for a configurable validity window - then a fresh approval is required.

AI Gateway Policies page showing MCP Tool Approval with the Policies tab, existing policies, and Add Approval Policy button

When to use

Use tool approvals when a tool is too risky to run unattended - deleting records, sending external communications or mutating production infrastructure - but you still want agents to use it with a human in the loop. For agent-turn pauses inside the Agent Harness (rather than Gateway policy), see Human checkpoints in the TrueForge docs.

How tool approvals work

A gated tools/call arrives at the MCP Gateway. The gateway matches the request against your tool approval policies by MCP server and tool name.
An approval request is created. The first call creates a request in pending state and notifies approvers through the policy’s notification target. Repeated calls for the same tool and requester reuse that pending request.
The caller gets an “approval pending” result. The tool is not executed. The client can retry the same call later.
Approvers are notified with a link to the request.
An approver approves or denies the request from the TrueFoundry UI, optionally recording a reason.
Approved calls flow through. Once approved, the same call (same MCP server, tool, and requester) executes until the grant expires. Every result includes approval metadata in _meta.
Grants expire. After the validity window ends (Once, or a time-based duration), the grant lapses and the next call raises a new approval request. A denial does not permanently block the requester - the next call also raises a new request.

Who can do what

Action	Who
Create, update or delete tool approval policies	Tenant administrators
Approve or deny requests for a specific MCP server	Tenant administrators and collaborators on that MCP server with the MCP Server Approver role

Tenant administrators can see every approval request in the tenant; MCP Server Approvers see requests for the servers they approve. To designate approvers, open the MCP server, go to Collaborators and add users or teams with the MCP Server Approver role. That role grants read access to the server plus the Approve MCP Server Actions permission - see Manage User Roles & Permissions.

Update MCP Server drawer showing Collaborators with MCP Server Manager and MCP Server Approver roles

If an MCP server referenced by a policy has no collaborators with the MCP Server Approver role, only tenant administrators can approve / deny requests.

Create a tool approval policy

Each policy names the MCP servers it gates, the tool groups that require approval, the validity window for grants, and the notification target for approvers.

Open Tool Approval policies

Navigate to AI Gateway → Policies → MCP Tool Approval and create a new policy.

Pick tools that require approval

In Pick specific tools that require approval, select an MCP server and choose an approval scope: specific tool names, destructive tools only, or all tools. For each selected tool or group, set approval validity (Once or a time-based duration).

New Approval Policy form showing calculator-r tools with multiply and divide selected, including Once and Time-based approval validity options

Configure notifications

Choose a notification target so approvers are alerted when a request is raised.

Configure Notification Channel for Approvers with SlackBot selected and a Slack channel name configured

Save and test

Save the policy, then call a gated tool through the MCP Gateway. Confirm callers receive the pending result and that approvers can approve or deny the request.

Approval scope

Each tool group in a policy uses an approval_scope to decide which tools on the MCP server require approval:

Scope	YAML value	What it gates
Named tools	`named`	Only the tools listed in `enabled_tools`
Destructive tools	`destructive`	Tools the MCP server marks as destructive (`destructiveHint: true`)
All tools	`all`	Every tool on the MCP server

When more than one scope could apply to the same tool, the gateway picks the most specific match, in this order: named > destructive > all So a named rule for multiply overrides a broader destructive or all-tools rule for that tool.

Approval validity

After an approver approves a request, the grant stays valid according to validity_mode:

UI option	YAML	Behavior
Once	`type: count-based` with `count: 1`	The approval covers a single execution. The next call needs a new approval.
Time-based	`type: time-based` with `duration_in_minutes`	The approval covers calls for that many minutes (for example, 10 or 30), then expires.

When multiple policies or tool groups gate the same tool, the most restrictive validity wins: Once > time-based 10 minutes > time-based 30 minutes Shorter (or single-use) grants always take precedence over longer ones.

Review pending requests

Open AI Gateway → Policies → MCP Tool Approval → Pending Requests to approve or deny gated calls. Each request shows the tool, policy, requester, approvers, validity window, and tool arguments.

Pending Requests tab listing divide and multiply approval requests with Approve and Deny actions

What callers see

While a request is pending (or after it has been denied and re-raised), the gateway returns a successful JSON-RPC result whose content asks the caller to wait - the tool is not executed:

{
  "content": [
    {
      "type": "text",
      "text": "Approval pending for request <request-id>. Awaiting human approval before execution. Reach out to user:alice@company.com."
    }
  ],
  "isError": false,
  "_meta": {
    "approval_status": "pending",
    "approval_request_id": "<request-id>",
    "reason": "Awaiting human approval before execution"
  }
}

Try Tool multiply playground showing approval_status pending and awaiting human approval message

Try Tool divide playground showing approval_status pending in the output panel

Once approved, tool results pass through unchanged with approval metadata merged into _meta:

"_meta": {
  "approval_status": "approved",
  "approval_request_id": "<request-id>"
}

Agents can inspect _meta.approval_status to distinguish a held call from a real tool result and retry later.

Try Tool multiply playground showing approval_status approved and the multiplication result 103680

Frequently asked questions

What happens when a grant expires?

The next call to the tool raises a fresh approval request and returns the “approval pending” result. Approvers are notified again, and the requester waits for a new decision.

Does denying a request block the user permanently?

No. A denial is recorded on that request, but the next call to the tool raises a new approval request. To durably block access to a tool, remove the user’s access to the MCP server or disable the tool instead.

Are approvals shared between users?

No. Grants are scoped to the requester (user, virtual account or other identity) plus the specific MCP server and tool. Each requester needs their own approval.

Which requests does a policy affect?

Only MCP tools/call requests routed through the MCP Gateway for the servers and tools the policy names.

What counts as a destructive tool?

Tools the MCP server annotates with destructiveHint: true. Use approval_scope: destructive to require approval for all of them without listing each name.

What if two policies gate the same tool?

The most specific approval scope wins (named over destructive over all), and the most restrictive validity wins (Once over shorter time-based windows over longer ones).

Get Started

LLM Gateway

MCP Registry and Gateway

Skills Registry

Prompt Registry

Guardrails and Security

Observability

Deployment

Admin Guide

Chat

Messages

Embeddings

Rerank

Responses

Image

Audio

Batch

Files

Fine-tuning

Moderations

Models

When to use

How tool approvals work

Who can do what

Create a tool approval policy

Approval scope

Approval validity

Review pending requests

What callers see

Frequently asked questions

​When to use

​How tool approvals work

​Who can do what

​Create a tool approval policy

​Approval scope

​Approval validity

​Review pending requests

​What callers see

​Frequently asked questions

When to use

How tool approvals work

Who can do what

Create a tool approval policy

Approval scope

Approval validity

Review pending requests

What callers see

Frequently asked questions