> ## 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-in-the-loop](/docs/agent-platform/agent-harness/human-in-the-loop).

## 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 `duration_in_minutes` from the approval, 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).

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

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

<Steps>
  <Step title="Open Tool Approval policies">
    Navigate to **AI Gateway → Policies → MCP Tool Approval** and create a new policy.
  </Step>

  <Step title="Pick tools that require approval">
    In **Pick specific tools that require approval**, select an MCP server and check the tools that need approval, or turn on **Select all tools for approval**. For each selected tool, set how long the grant stays valid after approval (for example, **30 Minutes**).
  </Step>

  <Step title="Configure notifications">
    Choose a notification target so approvers are alerted when a request is raised.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  If multiple policies gate the same tool for the same MCP server, the **most restrictive** policy wins - the one with the smallest `duration_in_minutes` validity window.
</Note>

## 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 <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"
  }
}
```

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

```json theme={"dark"}
"_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.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Which requests does a policy affect?">
    Only MCP `tools/call` requests routed through the MCP Gateway for the servers and tools the policy names.
  </Accordion>
</AccordionGroup>