NextPDF Connect HITL-Risikostufen

Auf einen Blick

Jedes Tool deklariert eine von vier Risikostufen. Die höchste Stufe, genehmigungspflichtig, wird beim ersten Aufruf nicht ausgeführt. Stattdessen gibt das ConfirmationGate ein einmalig verwendbares Challenge-Token zurück. Ein Agent muss dieses Token an einen Menschen weitergeben, der den erneuten Aufruf autorisiert.

Installation

composer require nextpdf/server

Konzeptioneller Überblick

Das Risikomodell umfasst genau vier geordnete Stufen:

Stufe	Wert	Bedeutung	Wirkung
safe	0	Nur lesend, keine Seiteneffekte	Automatische Ausführung
caution	1	Erzeugt oder verändert In-Memory-Zustand	Automatische Ausführung, im Audit-Log erfasst
review	2	Erzeugt Ausgaben, die missbraucht werden könnten	Automatische Ausführung, im Audit-Log erfasst
approval_required	3	Destruktiv, rechtlich relevant oder datenschutzkritisch	Menschliche Bestätigung erforderlich

Das Risiko eines Tools ergibt sich aus genau zwei Quellen: aus der Deklaration des Tools selbst und aus einem optionalen Konfigurations-Override des Betreibers. Eine dritte Quelle gibt es nicht. Das Modell führt eine Versionsnummer, und die MCP-initialize-Antwort legt diese Nummer offen, damit ein Client eine inkompatible Änderung erkennen kann. Audit-Logging greift ab der Stufe caution und darüber.

Eine automatisierte Aktion zurückzuhalten, bis ein Mensch sie autorisiert, setzt die Kontrolle genau dort an, wo die Automatisierung das Risiko einführt. Genau diese Stelle benennt IEC 31010 zur Kontrolle von Risiken, die durch menschliches Handeln eingeführt werden – am oder nahe dem Punkt der Einführung (IEC 31010:2019).

API-Oberfläche

Das ConfirmationGate

Wird ein approval_required-Tool ohne gültiges Token aufgerufen, gibt das Gate eine Challenge aus. Die Prüfung liefert eine von zwei Antwortformen zurück.

{ "allowed": true }

oder

{ "allowed": false, "challenge": "<human-readable text>", "token": "confirm_<nonce>" }

Der Challenge-Text nennt die Operation und ihre Beschreibung und warnt, wenn eine Zieldatei überschrieben würde. Er weist den Aufrufer an, dasselbe Tool erneut aufzurufen, wobei der Parameter _confirmation_token auf das ausgegebene Token gesetzt wird. Das Token läuft nach 300 Sekunden ab.

Die Token-Bindung ist bewusst so gewählt: Das Token ist an den Tool-Namen, eine zufällige Nonce und die TTL gebunden – nicht an die Argumente. Beim erneuten Versuch können MCP-Clients die Argumente mit anderer Schlüsselreihenfolge oder Normalisierung neu serialisieren; ein Hash über die Argumente würde daher legitime Bestätigungen ungültig machen. Das Token ist einmalig verwendbar; beim erneuten Aufruf wird es verbraucht und gibt den Aufruf genau einmal frei.

Darstellung je Transport

Das Gate wird bei jedem Transport durchgesetzt, über den Tools angesteuert werden:

MCP: Die Challenge wird in-band als erfolgreiche JSON-RPC-Antwort mit dem Challenge-Text als Inhalt zurückgegeben. Der Aufrufer ruft tools/call erneut mit arguments._confirmation_token auf.
REST und gRPC: Dasselbe Gate läuft im gemeinsamen Tool-Executor, bevor eine approval_required-Operation ausgeführt wird. Die Challenge erscheint in der Operationsantwort; der Aufrufer wiederholt die Operation mit dem Token.

Eingebauter Downgrade-Schutz

Ein Konfigurations-Override darf die Risikostufe eines Tools anheben, darf aber ein Tool, das per Design approval_required ist, niemals absenken. Der Konfigurations-Loader erzwingt eine fest definierte kritische Menge und wirft beim Laden eine Ausnahme, wenn ein Override ein Downgrade versucht. Der Server verweigert den Start, statt mit einem abgeschwächten Gate zu laufen.

Codebeispiel — Schnellstart

Lösen Sie eine Challenge aus, indem Sie mit output_pdf eine Datei schreiben:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"output_pdf","arguments":{"document_id":"<id>","file_path":"/var/lib/nextpdf/tmp/out.pdf"}}}
EOF

Die Antwort ist die Challenge, nicht die Datei. Rufen Sie das Tool mit dem ausgegebenen Token erneut auf:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"output_pdf","arguments":{"document_id":"<id>","file_path":"/var/lib/nextpdf/tmp/out.pdf","_confirmation_token":"confirm_<nonce>"}}}

Codebeispiel — Produktion

Heben Sie ein Tool, das normalerweise als caution eingestuft ist, für ein gehärtetes Deployment auf genehmigungspflichtig an:

nextpdf_mcp:
  risk_level_overrides:
    add_image: 3      # require human confirmation for image insertion

Ein Downgrade wird beim Laden abgewiesen, und der Server startet nicht. Beispielsweise ist es ein Downgrade, output_pdf unter 3 zu setzen.

Grenzfälle und Stolperfallen

output_pdf im base64-Modus löst das Gate nicht aus. Das Schreiben auf die Festplatte ist genehmigungspflichtig; die Rückgabe des PDF als base64 (ohne file_path) gilt als geringeres Risiko und läuft ohne Bestätigung.
Das Token ist kein Credential. Es authentifiziert den Aufrufer nicht und ersetzt bei vernetzten Transporten keinen API-Schlüssel. Es gibt nur einen bestimmten, durch das Gate gesperrten Aufruf innerhalb von 300 Sekunden genau einmal frei.
Jedes Mal eine neue Challenge. Wenn ein Token nicht weitergereicht wird oder abläuft, blockiert das Tool dadurch nicht dauerhaft; der nächste Aufruf gibt eine neue Challenge aus. Token werden in einem Single-Use-Token-Store mit periodischer Garbage Collection abgelegt.
Das Audit erfolgt unabhängig vom Ergebnis. Die Ausgabe einer Challenge, eine erfolgreiche Ausführung und eine fehlgeschlagene Ausführung ab der Stufe caution und darüber werden alle mit Tool-Namen und Risikostufe im Audit-Log erfasst.

Performance

Das Gate fügt einen Token-Store-Lookup und, bei einer Challenge, die Erzeugung eines Zufalls-Tokens hinzu. Es ist gegenüber den Kosten der gesperrten Operation vernachlässigbar und läuft nur für approval_required-Tools.

Sicherheitshinweise

Das Gate ist eine Eindämmungskontrolle, keine Authentifizierungskontrolle. Es stellt sicher, dass ein Mensch destruktive, rechtlich relevante oder datenschutzkritische Aktionen autorisiert, selbst wenn ein autonomer Agent das Tool ansteuert. Der Server erhebt für diese Operationen nicht den Anspruch, ohne menschliche Aufsicht zu arbeiten, und die Konfiguration kann das Gate nicht abschwächen. Kombinieren Sie es bei vernetzten Transporten mit dem API-Schlüssel-Modell und mit der Least-Privilege-Eingrenzung über enabled_tools. Siehe /connect/security-and-operations/.

Konformität

Aussage	Quelle	`reference_id`
Risiko am Punkt der (menschlichen) Einführung kontrollieren	IEC 31010:2019

Die Version des Risikomodells wird in der MCP-initialize-Antwort mitgeführt, damit Clients eine inkompatible Änderung erkennen können. Das Wire-Format ist unter /transports/mcp/ dokumentiert.

Kommerzieller Kontext

Premium-Tools deklarieren ihre eigene Risikostufe anhand desselben vierstufigen Modells. Destruktive Premium-Operationen (zum Beispiel Schwärzung) werden durch denselben Mechanismus gesperrt. Das Gate ist Teil des Servers, nicht des Premium-Pakets.

Siehe auch

/connect/tool-catalog/ — die Risikostufe jedes verifizierten Core-Tools
/connect/configuration/ — der ausschließlich anhebende Risiko-Override
/connect/security-and-operations/ — wie das Gate ins Bedrohungsmodell passt
/transports/mcp/ — das In-band-Wire-Format der Challenge
/connect/overview/ — wo das Gate in der Architektur sitzt