Niveles de riesgo HITL de NextPDF Connect

Resumen general

Cada herramienta declara uno de cuatro niveles de riesgo. El nivel más alto, que requiere aprobación, no se ejecuta en la primera llamada. En su lugar, ConfirmationGate devuelve un token de desafío de un solo uso, y un agente debe transmitir ese token a una persona para que autorice la nueva invocación.

Instalación

composer require nextpdf/server

Panorama conceptual

El modelo de riesgo define exactamente cuatro niveles ordenados:

Nivel	Valor	Significado	Efecto
safe	0	Solo lectura, sin efectos secundarios	Ejecución automática
caution	1	Crea o modifica estado en memoria	Ejecución automática, registrada en la auditoría
review	2	Produce una salida que podría usarse indebidamente	Ejecución automática, registrada en la auditoría
approval_required	3	Destructivo, legal o crítico para la privacidad	Se requiere confirmación humana

El riesgo de una herramienta procede exactamente de dos fuentes: la declaración de la propia herramienta y una anulación opcional de configuración aplicada por el operador. No existe una tercera fuente. El modelo incluye un número de versión, y la respuesta de initialize de MCP lo expone para que un cliente pueda detectar un cambio incompatible. El registro de auditoría se aplica desde el nivel caution en adelante.

Retener una acción automatizada hasta que una persona la autorice coloca un control exactamente donde la automatización introduce riesgo. Esta es la posición que la norma IEC 31010 identifica para controlar el riesgo introducido mediante la acción humana, en el punto de introducción o cerca de él (IEC 31010:2019).

Superficie de la API

El ConfirmationGate

Cuando se invoca una herramienta approval_required sin un token válido, la compuerta emite un desafío. La comprobación devuelve una de estas dos formas.

{ "allowed": true }

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

El texto del desafío identifica la operación y su descripción, y advierte cuando se sobrescribiría un archivo de destino. Indica a quien llama que vuelva a invocar la misma herramienta con un parámetro _confirmation_token establecido en el token emitido. El token caduca en 300 segundos.

La vinculación del token es deliberada: el token vincula el nombre de la herramienta, un nonce aleatorio y el TTL, no los argumentos. En un reintento, los clientes de MCP pueden volver a serializar los argumentos con un orden de claves o una normalización diferentes, por lo que aplicar un hash a los argumentos rompería confirmaciones legítimas. El token es de un solo uso; al consumirlo en la nueva invocación, la llamada se permite exactamente una vez.

Exposición por transporte

La compuerta se aplica en todos los transportes que ejecutan herramientas:

MCP: el desafío se devuelve en banda como una respuesta JSON-RPC válida cuyo contenido es el texto del desafío. Quien llama vuelve a invocar tools/call con arguments._confirmation_token.
REST y gRPC: la misma compuerta se ejecuta en el ejecutor de herramientas compartido antes de una operación approval_required. El desafío se expone en la respuesta de la operación; quien llama repite la operación con el token.

Protección integrada contra degradación

Una anulación de configuración puede elevar el nivel de riesgo de una herramienta, pero nunca puede reducir el de una herramienta que es approval_required por diseño. El cargador de configuración aplica un conjunto crítico fijo y lanza una excepción durante la carga si una anulación intenta una degradación. El servidor se niega a arrancar en lugar de funcionar con una compuerta debilitada.

Ejemplo de código: inicio rápido

Activa un desafío al escribir un archivo con 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

La respuesta es el desafío, no el archivo. Vuelve a invocar la herramienta con el token emitido:

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

Ejemplo de código: producción

Eleva a approval-required una herramienta que normalmente es caution para un despliegue reforzado:

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

Una degradación se rechaza durante la carga y el servidor no arranca. Por ejemplo, fijar output_pdf por debajo de 3 es una degradación.

Casos límite y trampas

output_pdf en modo base64 no activa la compuerta. Escribir en disco requiere aprobación; devolver el PDF como base64 (sin file_path) se trata como un riesgo menor y se ejecuta sin confirmación.
El token no es una credencial. No autentica a quien llama y no reemplaza una clave de API en los transportes de red. Solo libera, una única vez, una llamada controlada específica dentro de 300 segundos.
Un desafío nuevo cada vez. No transmitir un token o dejar que caduque no bloquea la herramienta de forma permanente; la siguiente llamada emite un nuevo desafío. Los tokens se guardan en un almacén de tokens de un solo uso con recolección periódica de basura.
La auditoría se registra independientemente del resultado. La emisión de un desafío, una ejecución correcta y una ejecución fallida desde el nivel caution en adelante se registran todas en la auditoría con el nombre de la herramienta y el nivel de riesgo.

Rendimiento

La compuerta añade una búsqueda en el almacén de tokens y, ante un desafío, la generación de un token aleatorio. Es insignificante frente al costo de la operación controlada y solo se ejecuta para herramientas approval_required.

Notas de seguridad

La compuerta es un control de contención, no un control de autenticación. Garantiza que una persona autorice las acciones destructivas, legales o críticas para la privacidad incluso cuando un agente autónomo ejecuta la herramienta. Para estas operaciones, el servidor no afirma funcionar sin supervisión humana, y la configuración no puede debilitar la compuerta. Combínala con el modelo de claves de API en los transportes de red y con el alcance de mínimo privilegio de enabled_tools. Consulta /connect/security-and-operations/.

Conformidad

Afirmación	Fuente	`reference_id`
Controlar el riesgo en el punto de introducción (humana)	IEC 31010:2019

La versión del modelo de riesgo se transmite en la respuesta de initialize de MCP para que los clientes puedan detectar un cambio incompatible. El formato de transmisión está documentado en /transports/mcp/.

Contexto comercial

Las herramientas Premium declaran su propio nivel de riesgo con el mismo modelo de cuatro niveles. Las operaciones Premium destructivas (por ejemplo, la redacción) se controlan mediante el mismo mecanismo. La compuerta forma parte del servidor, no del paquete Premium.

Véase también

/connect/tool-catalog/ — el nivel de riesgo de cada herramienta central verificada
/connect/configuration/ — la anulación de riesgo que solo permite elevarlo
/connect/security-and-operations/ — cómo encaja la compuerta en el modelo de amenazas
/transports/mcp/ — el formato de transmisión del desafío en banda
/connect/overview/ — dónde se ubica la compuerta en la arquitectura