Tool Policies

Tool policies define what happens when an agent attempts to call an MCP tool. Policies are evaluated in order of specificity — the most specific match wins.

Resolution Order

Priority	Scope	Description
1 (highest)	Agent + Tool	Both `agent_id` AND `mcp_tool_id` set — applies only to this specific combination
2	Tool only	`mcp_tool_id` set, `agent_id` null — applies to all agents for this tool
3	Agent only	`agent_id` set, `mcp_tool_id` null — applies to all tools for this agent
4 (default)	None	No matching policy found — ALLOW (configurable)

Creating Policies

Via the dashboard

Navigate to MCP Gateway → Tool Policies and click Create Policy. Choose the action and optionally the scope for a specific tool or a specific agent.

Via the API

curl -X POST /api/v1/mcp/policies \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "action": "DENY",
    "mcp_tool_id": "clxyz...",
    "agent_id": "agent_123",
    "reason": "Shell execution blocked for this agent"
  }'

All fields except action are optional. If both mcp_tool_id and agent_id are omitted, a project-wide default is created.

Connector Template Policies

When using a connector template (Salesforce, Copilot, ServiceNow), policies are automatically created with is_auto_generated: true. These follow best practices:

Read operations → ALLOW or LOG_ONLY
Write/update operations → LOG_ONLY (monitored)
Delete operations → REQUIRE_APPROVAL
Bulk export / code execution → DENY
Admin operations → DENY

Auto-generated policies can be edited or deleted just like any other policy.

Emergency Stop

POST /api/v1/mcp/emergency-stop immediately forces DENY for all MCP activity:

Scope	Effect
`"scope": "all"`	Blocks all MCP servers for the project
`"scope": "server"`	Blocks a specific server (`target_id` required)
`"scope": "agent"`	Creates a DENY-All policy for a specific agent (`target_id` required)

All pending approval requests are marked as expired. An audit trace with shouldAnchor: true is created for Flare attestation.