Tool Policies

Who admits an MCP tool, which rule applies to its calls, and how rules for single agents can only get stricter.

Tool policies define what happens when an agent calls an MCP tool. Before any rule applies, the tool must be admitted.

Admission: only admitted tools serve calls

A server is approved, a tool is admitted. Every tool is in one of three states:

State	Meaning	Calls
admitted	An Admin admitted its current state (name, description, parameters) with a rule.	by the rule
not admitted	No admission yet, for example because the tool appeared after the approval.	blocked (`-32002`)
changed since the admission	Name, description or parameters differ from the admitted state.	blocked (`-32002`)

Tools are admitted in two ways, both Admin actions:

With the server's approval. The approval dialog lists every tool of the last successful scan with a proposed rule; you can change each rule. Approving is possible only after a successful scan. A server that offers no tools is approved without tools; tools it offers later are admitted one by one.
One by one on an active server, for tools that are not admitted or changed: on the tools page (/integration/mcp/{id}/tools), each on its own or with "Accept proposals (N)" for all waiting tools.

A scan admits nothing and sets no rule. It records the current state of each tool; calls are checked against the state an Admin admitted. Resuming a paused server admits nothing either: a changed tool stays blocked until an Admin admits it again.

Proposals

For every tool that awaits a decision, Palveron proposes a rule. A proposal decides no call; only the rule an Admin confirms takes effect.

Tool action	Proposal
reads (`read`)	`ALLOW`
writes (`write`)	`LOG_ONLY`
deletes, sends, executes, not recognized	`REQUIRE_APPROVAL`

When one of the templates Palveron maintains names a stricter rule for a tool, the stricter proposal applies (source "template"); only then can a proposal be DENY. The risk level decides no proposal.

Which rule applies

A policy applies to a tool (mcp_tool_id), to an agent (agent_id), or to both. At call time:

The server-wide rule of a tool (no agent) is the ceiling for every agent. Among several server-wide rules the strictest wins:
```
DENY  >  REQUIRE_APPROVAL  >  LOG_ONLY  >  ALLOW
```
A rule for an agent can only tighten that ceiling, to REQUIRE_APPROVAL or DENY. An agent rule ALLOW or LOG_ONLY would never take effect and is refused when it is created (mcp_agent_rule_ineffective).
Without a rule the call is held for approval, never passed (-32004).
An unknown stored value blocks the call.
The agent's permission model can tighten a call further; an allowing tool rule never lifts its block or approval requirement.

The tools page

The per-server tools page (/integration/mcp/{id}/tools) shows for every tool:

the admission state (admitted, not admitted, changed since the admission) and, for waiting tools, the proposal with its source
the action and the risk
the tool rule (policy_action) and where it comes from: "Set automatically by Palveron" for rules the system created, "Confirmed by an admin" for rules from an admission or a rule change (is_auto_generated). Without a rule it reads "only with approval".

Admins change the rule of an admitted tool on the tools page. Loosening a rule asks for confirmation, because it reduces protection. Editors see every state and can scan; an Admin decides on approval, admission and rules.

Creating policies 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"
  }'

action is required, plus at least mcp_tool_id or agent_id; a policy with neither matches no call and is refused. With agent_id, only REQUIRE_APPROVAL and DENY are accepted. Creating a stricter policy is an Editor action; an allowing one (ALLOW, LOG_ONLY) needs an Admin.

Changing or removing a rule

There is no update endpoint for MCP policies. To change a tool's server-wide rule, an Admin sets it via POST /api/v1/mcp/servers/{id}/tools/{tool_id}/verdict. This replaces the tool's server-wide rules with the new one, so loosening takes effect too. To remove a policy entirely, an Admin deletes it (DELETE /api/v1/mcp/policies/{id}); without a rule the call is then held for approval.

Targeted MCP stop

POST /api/v1/mcp/emergency-stop immediately blocks one specific target. It is an Admin action and is recorded in the admin-audit trail. To stop the whole project at once, use the project emergency stop instead.

Scope	Effect
`"scope": "server"`	Blocks a specific server (`target_id` required); a server that is not `ACTIVE` stays unchanged
`"scope": "agent"`	Blocks a specific agent and ends its open approvals (`target_id` required)

The former "scope": "all" has been removed and is refused with mcp_scope_all_removed. The target's open approval requests are marked as expired, and the stop is recorded as a log entry for Flare attestation. A suspended agent is checked before any other state and named as the cause (AGENT_EMERGENCY_STOP).