NextPDF Connect HITL-risiconiveaus

In een oogopslag

Elke tool declareert een van de vier risiconiveaus. Het hoogste niveau, approval-required, wordt bij de eerste aanroep niet uitgevoerd. In plaats daarvan retourneert de ConfirmationGate een uitdagingstoken voor eenmalig gebruik. Een agent moet dat token doorgeven aan een mens, die de tweede aanroep autoriseert.

Installeren

composer require nextpdf/server

Conceptueel overzicht

Het risicomodel heeft precies vier geordende niveaus:

Niveau	Waarde	Betekenis	Effect
safe	0	Alleen-lezen, geen neveneffecten	Automatisch uitvoeren
caution	1	Maakt of wijzigt status in het geheugen	Automatisch uitvoeren, vastgelegd in het auditlogboek
review	2	Produceert uitvoer die misbruikt kan worden	Automatisch uitvoeren, vastgelegd in het auditlogboek
approval_required	3	Destructief, juridisch of privacykritisch	Menselijke bevestiging vereist

Het risico van een tool komt voort uit precies twee bronnen: de declaratie van de tool zelf en een optionele configuratieoverschrijving door de operator. Er is geen derde bron. Het model heeft een versienummer. Het MCP-antwoord op initialize stelt dat nummer beschikbaar, zodat een client een incompatibele wijziging kan detecteren. Auditlogging geldt vanaf caution en hoger.

Een geautomatiseerde actie tegenhouden totdat een mens deze autoriseert, plaatst de beheersmaatregel precies daar waar de automatisering risico introduceert. IEC 31010 benoemt dit als de plaats om risico te beheersen dat via menselijk handelen wordt geïntroduceerd, op of nabij het punt van introductie (IEC 31010:2019).

API-oppervlak

De ConfirmationGate

Wanneer je een approval_required-tool zonder geldig token aanroept, geeft de gate een uitdaging uit. De controle retourneert een van deze twee vormen.

{ "allowed": true }

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

De uitdagingstekst benoemt de bewerking en de bijbehorende beschrijving. De tekst waarschuwt ook wanneer een doelbestand zou worden overschreven. De tekst instrueert de aanroeper om dezelfde tool opnieuw aan te roepen met een _confirmation_token-parameter die is ingesteld op het uitgegeven token. Het token verloopt na 300 seconden.

De tokenbinding is bewust gekozen: het token bindt de toolnaam, een willekeurige nonce en de TTL — niet de argumenten. Bij een nieuwe poging kunnen MCP-clients de argumenten opnieuw serialiseren met een andere sleutelvolgorde of normalisatie, waardoor het hashen van de argumenten geldige bevestigingen zou laten mislukken. Het token is voor eenmalig gebruik. Bij de nieuwe aanroep wordt het token verbruikt en staat het de aanroep precies eenmaal toe.

Weergave per transport

De gate wordt afgedwongen op elk transport dat tools aanstuurt:

MCP: de uitdaging wordt in-band geretourneerd als een geslaagd JSON-RPC-antwoord met de uitdagingstekst als inhoud. De aanroeper roept tools/call opnieuw aan met arguments._confirmation_token.
REST en gRPC: dezelfde gate draait in de gedeelde tool-executor vóór een approval_required-bewerking. De uitdaging verschijnt in het antwoord op de bewerking. De aanroeper herhaalt de bewerking met het token.

Ingebouwde downgradebescherming

Een configuratieoverschrijving mag het risiconiveau van een tool verhogen, maar mag nooit een tool verlagen die door ontwerp approval_required is. De configuratieloader dwingt een vaste kritieke set af en geeft bij het laden een fout als een overschrijving een downgrade probeert. De server weigert te starten in plaats van met een verzwakte gate te draaien.

Codevoorbeeld — Snel aan de slag

Activeer een uitdaging door een bestand te schrijven met output_pdf:

./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

Het antwoord is de uitdaging, niet het bestand. Roep opnieuw aan met het uitgegeven token:

{"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>"}}}

Codevoorbeeld — Productie

Verhoog een tool die normaal caution is naar approval-required voor een geharde uitrol:

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

Een downgrade wordt bij het laden geweigerd en de server start niet. Het instellen van output_pdf lager dan 3 is bijvoorbeeld een downgrade.

Randgevallen en valkuilen

output_pdf in base64-modus gebruikt geen gate. Schrijven naar schijf is approval-required; het retourneren van de PDF als base64 (zonder file_path) wordt als een lager risico behandeld en draait zonder bevestiging.
Het token is geen credential. Het authenticeert de aanroeper niet en vervangt geen API-sleutel op transporten via het netwerk. Het geeft slechts één specifieke door de gate afgeschermde aanroep eenmaal vrij, binnen 300 seconden.
Elke keer een nieuwe uitdaging. Als je geen token doorgeeft, of als het verloopt, blokkeert dat de tool niet permanent. De volgende aanroep geeft een nieuwe uitdaging uit. Tokens worden opgeslagen in een tokenopslag voor eenmalig gebruik met periodieke garbagecollection.
Audit vindt plaats ongeacht de uitkomst. Het uitgeven van een uitdaging, een geslaagde uitvoering en een mislukte uitvoering vanaf caution en hoger worden allemaal vastgelegd in het auditlogboek met de toolnaam en het risiconiveau.

Prestaties

De gate voegt een opzoekactie in de tokenopslag toe en, bij een uitdaging, het genereren van een willekeurig token. Die kosten zijn verwaarloosbaar naast de door de gate afgeschermde bewerking en gelden alleen voor approval_required-tools.

Beveiligingsnotities

De gate is een beheersmaatregel voor inperking, geen beheersmaatregel voor authenticatie. De gate zorgt ervoor dat een mens destructieve, juridische of privacykritische acties autoriseert, zelfs wanneer een autonome agent de tool aanstuurt. Voor deze bewerkingen claimt de server niet zonder menselijk toezicht te werken, en configuratie kan de gate niet verzwakken. Combineer de gate met het API-sleutelmodel op transporten via het netwerk en met de least-privilege-scoping van enabled_tools. Zie /connect/security-and-operations/.

Conformiteit

Bewering	Bron	`reference_id`
Risico beheersen op het punt van (menselijke) introductie	IEC 31010:2019

Het MCP-antwoord op initialize bevat de versie van het risicomodel, zodat clients een incompatibele wijziging kunnen detecteren. Het wire-formaat is gedocumenteerd op /transports/mcp/.

Commerciële context

Premium-tools declareren hun eigen risiconiveau met hetzelfde model van vier niveaus. Destructieve Premium-bewerkingen, zoals redactie, gebruiken dezelfde gate. De gate maakt deel uit van de server, niet van het Premium-pakket.

Zie ook

/connect/tool-catalog/ — risiconiveaus voor elke geverifieerde core-tool
/connect/configuration/ — de risico-overschrijving waarmee je alleen kunt verhogen
/connect/security-and-operations/ — hoe de gate past in het dreigingsmodel
/transports/mcp/ — het in-band wire-formaat van de uitdaging
/connect/overview/ — waar de gate zich in de architectuur bevindt