MCP approvals

Overview

The Approvals page is where you review and decide on tool execution requests that need human sign-off. When a tool is marked as "requires approval" in the Tool Catalog, every invocation pauses here until an admin approves or denies it.

You'll find it at AI Gateway > MCP Gateway > Approvals.

Tabs

The page has two tabs:

• Pending: Shows approval requests waiting for a decision. The tab label includes a count when requests are queued (e.g., "Pending (3)").
• History: Shows previously approved and denied requests.

Pending requests

Each pending request card shows:

Approving or denying a request

Each pending request has two action buttons on the right:

• Approve: (green button) Allows the agent to proceed with the tool call.
• Deny: (red outlined button) Blocks the tool call. The agent will receive an error.

Clicking either button opens a confirmation modal where you can optionally add a reason for your decision. The reason is stored and visible in the history tab.

1. Click Approve or Deny on a pending request.
2. In the confirmation modal, optionally type a reason (e.g., "Verified the query is safe" or "Agent shouldn't access production data").
3. Click the confirm button to submit your decision.
4. The request disappears from the Pending tab and appears in History.

Request expiration

Each approval request has an expiration window. If no one approves or denies within this window, the request expires automatically and the agent receives an error.

The expiration time is configured in the gateway settings (mcp_approval_expiry_seconds). Expired requests are cleaned up by a scheduled job.

Decision history

The History tab shows all decided requests (approved and denied). Each entry includes everything from the pending view, plus:

• Decision status: The chip shows "approved" or "denied" instead of "pending".
• Decided by: The name of the user who made the decision.
• Decided at: Timestamp of the decision.
• Decision reason: The reason entered at decision time, if any.

History is paginated. The last 50 decisions are loaded by default.

How agents interact with approvals

When an agent calls a tool that requires approval, here's what happens from the agent's perspective:

1. The agent sends a tools/call request to POST /v1/mcp.
2. The gateway returns a JSON-RPC error with code -32001 and a data payload containing the approval_id, poll_endpoint, and expires_at.
3. The agent polls GET /v1/mcp/approvals/{approval_id}/status periodically to check if the request was approved.
4. Once the status is "approved", the agent retries the original tools/call request.
5. If the status is "denied" or "expired", the agent handles the rejection.

// Error response when approval is required
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Tool requires approval",
    "data": {
      "approval_id": 42,
      "poll_endpoint": "/v1/mcp/approvals/42/status",
      "expires_at": "2026-04-20T15:30:00+00:00"
    }
  }
}

Empty states

When there are no pending approvals, the page shows: "No pending approvals" with a tip explaining how to trigger them (mark a tool as "requires approval" in the Tool Catalog, then call it with an agent key).

When there's no history yet, the message is: "No approval history yet. Approved or denied requests will appear here."

Permissions

Viewing pending requests and history is available to all authenticated users. Approving and denying requests requires the Admin role.