Уровни риска HITL в NextPDF Connect

Коротко о главном

Каждый инструмент объявляет один из четырёх уровней риска. Инструмент с наивысшим уровнем, approval-required, не выполняется при первом вызове. Вместо выполнения ConfirmationGate возвращает одноразовый токен проверки. Агент должен передать этот токен человеку, который авторизует повторный вызов.

Установка

composer require nextpdf/server

Концептуальный обзор

Модель риска имеет ровно четыре упорядоченных уровня:

Уровень	Значение	Смысл	Эффект
safe (безопасный)	0	Только чтение, без побочных эффектов	Автоматическое выполнение
caution (осторожность)	1	Создаёт или изменяет состояние в памяти	Автоматическое выполнение, с записью в журнал аудита
review (проверка)	2	Создаёт результат, который может быть использован не по назначению	Автоматическое выполнение, с записью в журнал аудита
approval_required (требуется подтверждение)	3	Деструктивные, юридически значимые или критичные для конфиденциальности	Требуется подтверждение человеком

Уровень риска инструмента определяется только двумя источниками: собственным объявлением инструмента и необязательным переопределением в конфигурации оператора. Третьего источника нет. У модели есть номер версии. Ответ MCP initialize передаёт этот номер, чтобы клиент мог обнаружить несовместимое изменение. Запись в журнал аудита выполняется для уровня caution и выше.

Если автоматизированное действие удерживается до авторизации человеком, контроль оказывается там, где автоматизация вносит риск. В терминах IEC 31010 это место для контроля риска, привносимого действиями человека, в точке его внесения или рядом с ней (IEC 31010:2019).

Поверхность API

ConfirmationGate (шлюз подтверждения)

Когда вы вызываете инструмент уровня approval_required без действительного токена, шлюз выдаёт проверочный запрос. Проверка возвращает одну из двух форм.

{ "allowed": true }

или

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

Текст проверочного запроса указывает операцию и её описание. Он также предупреждает, если целевой файл будет перезаписан. В нём указано, что вызывающей стороне нужно повторно вызвать тот же инструмент с параметром _confirmation_token со значением выданного токена. Токен истекает через 300 секунд.

Такая привязка токена сделана намеренно: токен привязан к имени инструмента, случайному nonce и TTL — но не к аргументам. При повторной попытке клиенты MCP могут заново сериализовать аргументы с другим порядком ключей или нормализацией, поэтому хеширование аргументов делало бы корректные подтверждения недействительными. Токен одноразовый. При повторном вызове он разрешает выполнение ровно один раз.

Отображение по транспортам

Шлюз применяется на каждом транспорте, который управляет инструментами:

MCP: проверочный запрос возвращается по тому же каналу в виде успешного ответа JSON-RPC; его содержимое — текст проверочного запроса. Вызывающая сторона повторно вызывает tools/call с arguments._confirmation_token.
REST и gRPC: тот же шлюз выполняется в общем исполнителе инструментов перед операцией approval_required. Проверочный запрос появляется в ответе операции. Вызывающая сторона повторяет операцию с токеном.

Встроенная защита от понижения уровня

Переопределение в конфигурации может повысить уровень риска инструмента, но никогда не может понизить уровень инструмента, который по своему замыслу относится к approval_required. Загрузчик конфигурации применяет фиксированный набор критичных инструментов и выбрасывает исключение во время загрузки, если переопределение пытается понизить уровень. Сервер отказывается запускаться вместо того, чтобы работать с ослабленным шлюзом.

Пример кода — Быстрый старт

Получите проверочный запрос при записи файла с помощью 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

В ответ придёт проверочный запрос, а не файл. Повторите вызов с выданным токеном:

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

Пример кода — Продакшен

Повысьте инструмент, который обычно относится к caution, до approval-required для усиленного развёртывания:

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

Понижение отклоняется во время загрузки, и сервер не запускается. Например, установка output_pdf ниже 3 считается понижением.

Граничные случаи и подводные камни

output_pdf в режиме base64 не проходит через шлюз. Запись на диск относится к approval-required; возврат PDF в виде base64 (без file_path) считается более низким риском и выполняется без подтверждения.
Токен не является учётными данными. Он не аутентифицирует вызывающую сторону и не заменяет ключ API на сетевых транспортах. В течение 300 секунд он разрешает однократно выполнить только один конкретный вызов, заблокированный шлюзом.
Каждый раз новый проверочный запрос. Если токен не передан или срок его действия истёк, это не блокирует инструмент навсегда. Следующий вызов выдаёт новый проверочный запрос. Токены хранятся в хранилище одноразовых токенов с периодической сборкой мусора.
Аудит происходит независимо от исхода. Выдача проверочного запроса, успешное и неудачное выполнение для уровня caution и выше записываются в журнал аудита с указанием имени инструмента и уровня риска.

Производительность

Шлюз добавляет обращение к хранилищу токенов и, при проверочном запросе, генерацию случайного токена. Эти издержки пренебрежимо малы по сравнению с операцией, которую блокирует шлюз, и возникают только для инструментов approval_required.

Замечания по безопасности

Шлюз — это средство сдерживания, а не средство аутентификации. Он гарантирует, что человек авторизует деструктивные, юридически значимые или критичные для конфиденциальности действия, даже когда инструментом управляет автономный агент. Для этих операций сервер не заявляет работу без человеческого надзора, и конфигурация не может ослабить шлюз. Сочетайте его с моделью ключей API на сетевых транспортах и с ограничением по принципу наименьших привилегий через enabled_tools. См. /connect/security-and-operations/.

Соответствие

Утверждение	Источник	`reference_id`
Контролировать риск в точке его внесения (человеком)	IEC 31010:2019

Ответ MCP initialize содержит версию модели риска, чтобы клиенты могли обнаружить несовместимое изменение. Формат передачи описан на /transports/mcp/.

Коммерческий контекст

Инструменты Premium объявляют собственный уровень риска по той же четырёхуровневой модели. Деструктивные операции Premium, такие как редактирование (redaction), используют тот же шлюз. Шлюз является частью сервера, а не пакета Premium.

См. также

/connect/tool-catalog/ — уровни риска для каждого проверенного инструмента ядра
/connect/configuration/ — переопределение риска только в сторону повышения
/connect/security-and-operations/ — как шлюз вписывается в модель угроз
/transports/mcp/ — формат передачи проверочного запроса по тому же каналу
/connect/overview/ — где шлюз находится в архитектуре