Tool Policies

Tool policies define what happens when an agent attempts to call an MCP tool.

Resolution

A policy can be scoped by mcp_tool_id, by agent_id, or by both. At call time, all policies matching the tool/agent combination are considered and the most restrictive action wins:

DENY  >  REQUIRE_APPROVAL  >  LOG_ONLY  >  ALLOW

Unknown action values rank as DENY (fail-closed). When no policy matches, the call is allowed and the trace is explicitly marked as a default-allow (DEFAULT_ALLOW_NO_POLICY) so dashboards can distinguish it from an explicit ALLOW policy.

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": "ckagent...",
    "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 one of the 11 connector templates, 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, and the stop is recorded as an audit trace for Flare attestation.