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.

Auto-seeded verdicts (from the scan)

When a server is scanned, Palveron seeds a server-wide starting verdict for every discovered tool, derived from the tool's risk level. These are marked is_auto_generated: true, and any policy you set yourself takes precedence.

Risk level	Seeded verdict
LOW	`ALLOW`
MEDIUM	`LOG_ONLY`
HIGH	`REQUIRE_APPROVAL`
CRITICAL	`REQUIRE_APPROVAL`

No DENY is ever auto-seeded — the platform governs from the first connect without silently locking a server out; you decide where DENY belongs.

The Tools Cockpit

The per-server Tools Cockpit (/integration/mcp/{id}/tools) is where you review and govern each tool. For every tool it shows:

Risk and the plain-language consequence, next to the effective verdict (policy_action)
Whether the binding verdict was auto-seeded by Palveron or set by you (is_auto_generated)
The approval state: "unchanged since approval", "differs from the approved state" (drift → calls blocked until re-approval), or — for never-approved tools — the legacy "since last scan" signal (matches_approved)

Admins change a tool's verdict from the cockpit. Loosening a verdict (making it less restrictive) asks for confirmation, because it reduces protection.

Creating Policies

Via the dashboard

Open the Tools Cockpit (/integration/mcp/{id}/tools) and use the per-tool Change control (Admin) to set the verdict.

Via the API

curl -X POST https://gateway.palveron.com/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. Creating a policy is an Editor action.

Changing or removing a verdict

There is no update endpoint for MCP policies. To change a tool's server-wide verdict, an Admin sets it via POST /api/v1/mcp/servers/{id}/tools/{tool_id}/verdict — this collapses the tool's server-wide slot to the new verdict (so loosening actually takes effect, rather than being shadowed by "most restrictive wins"). To remove a policy entirely, an Admin deletes it (DELETE /api/v1/mcp/policies/{id}).

Emergency Stop

POST /api/v1/mcp/emergency-stop immediately forces DENY for all MCP activity. It is an Admin action and is recorded in the admin-audit trail.

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.

On this page