NextPDF Connect HITL 위험 등급

한눈에 보기

모든 도구는 네 가지 위험 수준 중 하나를 선언합니다. 가장 높은 수준인 승인 필요 도구는 첫 호출에서 실행되지 않습니다. 대신 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인 도구를 승인 필요로 높입니다:

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

다운그레이드는 로드 시점에 거부되며 서버가 시작되지 않습니다. 예를 들어 output_pdf를 3 미만으로 설정하는 것은 다운그레이드입니다.

엣지 케이스 및 주의 사항

base64 모드의 output_pdf는 게이트되지 않습니다. 디스크 쓰기는 승인 필요이지만, 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 도구는 동일한 4단계 모델을 사용하여 자체 위험 수준을 선언합니다. 파괴적인 Premium 작업(예: 편집 삭제)에는 동일한 메커니즘으로 게이트가 적용됩니다. 게이트는 Premium 패키지가 아니라 서버의 일부입니다.