MCP Tool Policies
How to control which MCP tools agents can invoke with per-tool allow, review, and block policies, and how decisions are logged in the audit trail.
MCP tool policies let you control which tools agents can invoke on each remote MCP server. This is the MCP equivalent of scope policies for connected accounts.
Policy Decisions
Each tool can be assigned one of three policies:
Allow
The tool call proceeds immediately without user intervention. Use this for tools you trust the agent to call autonomously.
Example: You might allow list_contacts on a CRM server since it only reads data.
Review
The tool call is paused, and you receive a notification asking you to approve or deny it. The agent waits (up to 5 minutes) for your decision.
The review prompt shows:
- The MCP server name.
- The tool being called (e.g.,
send_email). - A human-readable description of the action (e.g., "Allow sending email via CRM Server?").
If you do not respond within 5 minutes, the request times out and the agent receives an error.
Example: You might set send_email to review so you can verify the content before it is sent.
Block
The tool call is immediately rejected. The agent receives an error indicating the request was blocked by policy.
Example: You might block delete_all_records to prevent accidental data loss.
Policy Resolution Order
When an agent calls a tool, the policy resolver follows this hierarchy:
- Explicit tool policy — If you have set a policy for the specific tool name (e.g.,
send_email= review), that policy applies. - MCP default — If no explicit tool policy exists, the server-level default applies. This is configured as the
*tool in the policy editor. - Global default — If no MCP default is set, the global default from your user settings applies. This defaults to
review.
Protocol Methods Are Exempt
Policy enforcement only applies to tools/call requests — the actual tool invocations. MCP protocol-level methods are always allowed without policy checks:
initializeandnotifications/initialized(handshake)tools/list,prompts/list,resources/list(discovery)ping,logging/setLevel,completion/complete(housekeeping)- All
notifications/*methods
This ensures that tool discovery and connection management work regardless of policy settings.
Configuring Tool Policies
From the Settings Dialog
- Navigate to Settings > Connections.
- Find the MCP server you want to configure.
- Click the Policies button (shield icon) on the server row.
- The tool policy editor opens, showing:
- MCP Default — The fallback policy for tools without explicit rules. Set to "Default" to inherit from your global settings.
- Per-tool list — Every tool discovered on the server, with its name, description, and current policy.
- Use the toggle for each tool to set it to Allow, Review, Block, or Default.
- Click Save Policies to apply.
You can filter the tool list by name or description using the search box, and filter by policy decision using the dropdown.
From a Review Prompt
When a tool call triggers a review, the review prompt appears inline in the chat session. Along with the approve/deny buttons, the prompt offers an Always Allow option that sets an explicit "allow" policy for that tool. This lets you build up policies incrementally as you use the agent.
Audit Trail
Every MCP tool call is recorded in the MCP audit log with the following fields:
| Field | Description |
|---|---|
agentSlug | The agent that made the call |
remoteMcpId | The MCP server ID |
remoteMcpName | The MCP server display name |
method | The HTTP method (typically POST) |
requestPath | The JSON-RPC method (e.g., tools/call: search_contacts) |
statusCode | The HTTP status code of the upstream response |
durationMs | Round-trip time in milliseconds |
policyDecision | The policy outcome (see below) |
matchedTool | The tool name for tools/call requests |
Policy Decision Values
The policyDecision field in the audit log records the outcome of policy resolution:
- allow — The tool call was auto-approved by policy.
- approved_by_user — The tool call was in review and the user approved it.
- denied_by_user — The tool call was in review and the user denied it.
- block — The tool call was blocked by policy without prompting.
- review_timeout — The tool call was in review but the user did not respond within 5 minutes.
For protocol-level methods (initialize, tools/list, etc.), the policy decision is recorded as allow since these bypass policy enforcement.
You can review these entries in the Audit Logging interface.
Comparison with Scope Policies
| Scope Policies | Tool Policies | |
|---|---|---|
| Applies to | Connected accounts (OAuth APIs) | Remote MCP servers |
| Granularity | Per OAuth scope (e.g., gmail.send) | Per tool name (e.g., send_email) |
| Resolution | Most permissive scope wins | Single tool match |
| Default hierarchy | Scope -> Account default -> Global | Tool -> MCP default -> Global |
The core mechanics are the same: a three-tier hierarchy of explicit, default, and global policies with the same allow/review/block decisions.
Related
- Remote MCP Servers — How to register and manage MCP servers.
- Scope Policies — The equivalent policy system for connected accounts.
- Audit Logging — Review the full audit trail.