> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Tool Approvals
> Add human-in-the-loop approval for sensitive MCP tools on the Gateway. Set validity windows and notify approvers via Email, Slack, PagerDuty or MS Teams.
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](/docs/ai-gateway/mcp/mcp-overview), 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.
## 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](https://trueforge.dev/key-features/overview) in the TrueForge docs.
## How tool approvals work
1. **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.
2. **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.
3. **The caller gets an "approval pending" result.** The tool is not executed. The client can retry the same call later.
4. **Approvers are notified** with a link to the request.
5. **An approver approves or denies the request** from the TrueFoundry UI, optionally recording a reason.
6. **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`.
7. **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](/docs/platform/manage-user-roles-and-permissions#resource-level-roles-collaborators).
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.
Navigate to **AI Gateway → Policies → MCP Tool Approval** and create a new policy.
In **Pick specific tools that require approval**, select an MCP server and choose an [approval scope](#approval-scope): specific tool names, destructive tools only, or all tools. For each selected tool or group, set [approval validity](#approval-validity) (**Once** or a time-based duration).
Choose a notification target so approvers are alerted when a request is raised.
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.
## 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:
```json theme={"dark"}
{
"content": [
{
"type": "text",
"text": "Approval pending for request . Awaiting human approval before execution. Reach out to user:alice@company.com."
}
],
"isError": false,
"_meta": {
"approval_status": "pending",
"approval_request_id": "",
"reason": "Awaiting human approval before execution"
}
}
```
Once approved, tool results pass through unchanged with approval metadata merged into `_meta`:
```json theme={"dark"}
"_meta": {
"approval_status": "approved",
"approval_request_id": ""
}
```
Agents can inspect `_meta.approval_status` to distinguish a held call from a real tool result and retry later.
## Frequently asked questions
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.
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.
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.
Only MCP `tools/call` requests routed through the MCP Gateway for the servers and tools the policy names.
Tools the MCP server annotates with `destructiveHint: true`. Use `approval_scope: destructive` to require approval for all of them without listing each name.
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).