Tool-Richtlinien

Wer ein MCP-Werkzeug zulässt, welche Regel für seine Aufrufe gilt und wie Regeln für einzelne Agenten nur strenger werden.

Tool-Richtlinien legen fest, was geschieht, wenn ein Agent ein MCP-Werkzeug aufruft. Bevor eine Regel greift, muss das Werkzeug zugelassen sein.

Zulassung: nur zugelassene Werkzeuge bedienen Aufrufe

Ein Server wird genehmigt, ein Werkzeug wird zugelassen. Jedes Werkzeug ist in einem von drei Zuständen:

Zustand	Bedeutung	Aufrufe
zugelassen	Ein Admin hat den aktuellen Stand (Name, Beschreibung, Parameter) mit einer Regel zugelassen.	nach der Regel
nicht zugelassen	Noch keine Zulassung, etwa weil das Werkzeug nach der Genehmigung hinzukam.	gesperrt (`-32002`)
geändert seit der Zulassung	Name, Beschreibung oder Parameter weichen vom zugelassenen Stand ab.	gesperrt (`-32002`)

Zugelassen wird auf zwei Wegen, beides Admin-Aktionen:

Mit der Genehmigung des Servers. Der Genehmigungsdialog zeigt jedes Werkzeug des letzten erfolgreichen Scans mit einer vorgeschlagenen Regel; Sie können jede Regel ändern. Genehmigen ist erst nach einem erfolgreichen Scan möglich. Bietet der Server keine Werkzeuge an, wird er ohne Werkzeuge genehmigt; Werkzeuge, die er später anbietet, lassen Sie einzeln zu.
Einzeln auf einem aktiven Server, für nicht zugelassene und geänderte Werkzeuge: auf der Werkzeugseite (/integration/mcp/{id}/tools) einzeln oder mit „Vorschläge übernehmen (N)" für alle wartenden Werkzeuge.

Ein Scan lässt nichts zu und setzt keine Regel. Er merkt sich den aktuellen Stand jedes Werkzeugs; geprüft werden Aufrufe gegen den Stand, den ein Admin zugelassen hat. Das Fortsetzen eines pausierten Servers lässt ebenfalls nichts zu: Ein geändertes Werkzeug bleibt gesperrt, bis ein Admin es erneut zulässt.

Vorschläge

Für jedes Werkzeug, das auf eine Entscheidung wartet, schlägt Palveron eine Regel vor. Der Vorschlag entscheidet keinen Aufruf; wirksam ist nur die Regel, die ein Admin bestätigt.

Aktion des Werkzeugs	Vorschlag
liest (`read`)	`ALLOW`
schreibt (`write`)	`LOG_ONLY`
löscht, sendet, führt aus, nicht erkannt	`REQUIRE_APPROVAL`

Nennt eine von Palveron gepflegte Vorlage für ein Werkzeug eine strengere Regel, gilt der strengere Vorschlag (Quelle „Vorlage"); nur so kann ein Vorschlag DENY lauten. Die Risikostufe entscheidet über keinen Vorschlag.

Welche Regel gilt

Eine Richtlinie gilt für ein Werkzeug (mcp_tool_id), für einen Agenten (agent_id) oder für beides. Zur Aufrufzeit gilt:

Die serverweite Regel eines Werkzeugs (ohne Agent) ist die Obergrenze für jeden Agenten. Unter mehreren serverweiten Regeln gewinnt die strengste:
```
DENY  >  REQUIRE_APPROVAL  >  LOG_ONLY  >  ALLOW
```
Eine Regel für einen Agenten kann diese Obergrenze nur verschärfen, auf REQUIRE_APPROVAL oder DENY. Eine Agentenregel ALLOW oder LOG_ONLY würde nie wirken und wird beim Anlegen abgelehnt (mcp_agent_rule_ineffective).
Ohne Regel wird der Aufruf zur Freigabe vorgelegt, nie durchgelassen (-32004).
Ein unbekannter gespeicherter Wert sperrt den Aufruf.
Das Berechtigungsmodell des Agenten kann einen Aufruf zusätzlich verschärfen; eine erlaubende Werkzeugregel hebt dessen Sperre oder Freigabepflicht nie auf.

Die Werkzeugseite

Die Werkzeugseite je Server (/integration/mcp/{id}/tools) zeigt für jedes Werkzeug:

den Zulassungszustand (zugelassen, nicht zugelassen, geändert seit der Zulassung) und bei wartenden Werkzeugen den Vorschlag mit seiner Quelle
die Aktion und das Risiko
die Werkzeugregel (policy_action) und ihre Herkunft: „Von Palveron automatisch gesetzt" für Regeln, die das System angelegt hat, „Von einem Admin bestätigt" für Regeln aus einer Zulassung oder Regeländerung (is_auto_generated). Ohne Regel steht dort „nur mit Freigabe".

Admins ändern die Regel eines zugelassenen Werkzeugs auf der Werkzeugseite. Eine Regel zu lockern verlangt eine Bestätigung, weil es den Schutz verringert. Editoren sehen alle Zustände und können scannen; über Genehmigung, Zulassung und Regeln entscheidet ein Admin.

Richtlinien über die API anlegen

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 ist Pflicht, dazu mindestens mcp_tool_id oder agent_id; eine Richtlinie ohne beides passt auf keinen Aufruf und wird abgelehnt. Mit agent_id sind nur REQUIRE_APPROVAL und DENY erlaubt. Eine strengere Richtlinie anzulegen ist eine Editor-Aktion; eine erlaubende (ALLOW, LOG_ONLY) verlangt einen Admin.

Eine Regel ändern oder entfernen

Es gibt keinen Update-Endpunkt für MCP-Richtlinien. Um die serverweite Regel eines Werkzeugs zu ändern, setzt ein Admin sie über POST /api/v1/mcp/servers/{id}/tools/{tool_id}/verdict. Dabei werden die serverweiten Regeln des Werkzeugs durch die neue ersetzt, sodass auch ein Lockern wirkt. Um eine Richtlinie ganz zu entfernen, löscht ein Admin sie (DELETE /api/v1/mcp/policies/{id}); ohne Regel wird der Aufruf dann zur Freigabe vorgelegt.

Gezielter MCP-Stopp

POST /api/v1/mcp/emergency-stop blockiert sofort ein bestimmtes Ziel. Es ist eine Admin-Aktion und wird im Admin-Audit-Trail festgehalten. Um das ganze Projekt auf einmal zu stoppen, nutzen Sie die Notabschaltung des Projekts.

Scope	Wirkung
`"scope": "server"`	Blockiert einen bestimmten Server (`target_id` erforderlich); ein nicht `ACTIVE` Server bleibt unverändert
`"scope": "agent"`	Blockiert einen bestimmten Agenten und beendet seine offenen Freigaben (`target_id` erforderlich)

Das frühere "scope": "all" entfällt und wird mit mcp_scope_all_removed abgewiesen. Die offenen Freigabeanfragen des Ziels werden als abgelaufen markiert, und der Stopp wird als Protokolleintrag für die Flare-Attestierung festgehalten. Ein gesperrter Agent wird vor jedem anderen Zustand geprüft und als Ursache genannt (AGENT_EMERGENCY_STOP).