NextPDF Connect 문제 해결

한눈에 보기

대부분의 장애는 다섯 가지 범주 중 하나에 해당합니다. 형식이 잘못된 JSON-RPC 핸드셰이크, 누락된 API 키, 현재 티어에 설치되지 않은 도구, 응답하지 않은 확인 챌린지, 워커 간에 공유되지 않는 스토어입니다. 각 범주에는 고유한 징후가 있습니다.

설치

composer require nextpdf/server

개념 개요

MCP 전송 계층은 표준 코드가 포함된 JSON-RPC 2.0 오류 객체를 반환합니다. REST 전송 계층은 RFC 7807 problem-details 문서를 반환합니다. 각 문서에는 해당 조건을 식별하는 type URL이 포함되어 있습니다. 환경 문제는 진단 도구(diagnostic.doctor, diagnostic.capabilities)부터 확인하세요. 이 도구들은 항상 코어 카탈로그에 포함됩니다.

API 표면

MCP JSON-RPC 오류 코드

코드	이름	원인
`-32700`	파싱 오류	해당 줄이 유효한 JSON이 아니었습니다
`-32600`	잘못된 요청	JSON-RPC 2.0 메시지가 아님(`jsonrpc`/`method` 누락)
`-32601`	메서드를 찾을 수 없음	허용된 메서드 이외의 메서드: `initialize`, `tools/list`, `tools/call`
`-32602`	잘못된 매개변수	대상 `tools/call`에서 `params.name` 누락
`-32603`	내부 오류	실행 중 도구에서 예외 발생

도구가 실패를 정상적으로 처리할 때는 이러한 코드를 사용하지 않습니다. 대신 result에 isError: true를 설정하고, 알 수 없는 도구, 정책에 의한 비활성화, 잘못된 인수 등의 텍스트 설명을 담은 성공적인 JSON-RPC 응답을 반환합니다.

REST problem-details 유형

HTTP	`type` 슬러그	원인
`401`	`unauthorized`	누락/잘못됨/비활성화/만료된 API 키
`403`	`capability-denied`	키 티어에 해당 작업 권한이 없음
`413`	`payload-too-large` / `tier-payload-exceeded`	본문이 전역 또는 티어 상한을 초과함
`422`	`validation-failed`	요청 본문이 스키마 검증에 실패함
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	속도 제한에 도달함
`404`	`not-found`	알 수 없는 경로 또는 job/session id
`504`	(요청 시간 초과)	작업이 티어 시간 초과 한도를 넘음

코드 예제 — 빠른 시작

환경 상태 점검을 실행하세요. 문서나 확인 절차는 필요하지 않습니다.

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"diag","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"diagnostic.doctor","arguments":{}}}
EOF

코드 예제 — 프로덕션

“누락된 도구” 문제를 디버깅하기 전에, 이 배포가 어떤 도구를 노출하는지 확인하세요.

./vendor/bin/generate-skills --dry-run --list-tools

또는 실행 중인 REST 서버를 대상으로 다음을 실행하세요.

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

엣지 케이스와 주의 사항

Pro/Enterprise 도구에서 “알 수 없는 도구”가 발생함. 해당 도구의 패키지가 설치되지 않았습니다. 레지스트리는 프로바이더 클래스를 탐색하며 존재하지 않는 티어는 경고 없이 건너뜁니다. 이는 버그가 아니라 예상 동작입니다. 서버와 함께 nextpdf/premium을 설치하거나 코어 도구를 사용하세요. 오류 메시지에는 설치 경로가 포함됩니다.
enabled_tools에 구성한 도구가 나타나지 않음. 허용 목록은 발견된 도구와의 교집합으로 적용됩니다. 레지스트리가 찾지 못한 도구는 추가할 수 없습니다. 티어 설치 상태와 환경 게이트를 확인하세요. 예를 들어, parse_pdf는 NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED를 통해 옵트인됩니다.
tools/call이 토큰을 요청하는 텍스트를 반환함. 이는 오류가 아니라 확인 챌린지입니다. 300초 이내에 _confirmation_token을 발급된 토큰으로 설정하여 도구를 다시 호출하세요. 자세한 내용은 /connect/hitl-risk-tiers/를 참고하세요.
알림 줄에서 출력이 생성되지 않음. 이는 정상 동작입니다. id가 없는 JSON-RPC 메시지는 알림이며, 핸들러는 아무것도 반환하지 않습니다. 응답을 받으려면 id가 포함된 요청을 보내세요.
반복된 요청 id가 오래된 응답을 반환함. 핸들러는 64개 항목 버퍼에서 요청 id를 기준으로 중복을 제거합니다. 각 논리적 요청마다 새로운 id를 사용하세요.
워커 간 속도 제한이 비정상적으로 동작함. 인메모리 스토어는 워커별로 분리되어 있습니다. 공유 카운팅을 사용하려면 NEXTPDF_REDIS_HOST를 설정하고 ext-redis를 설치하세요. 자세한 내용은 /connect/deployment/를 참고하세요.
요청 사이에 문서가 사라짐. 인메모리 문서 스토어는 워커별로 분리되어 있으며 TTL(document_ttl, 기본값 1800 s)에 의해 제한됩니다. 워커 간 문서 연속성을 위해 Redis 기반 스토어나 세션 엔드포인트를 사용하거나 전체 작업 집합을 하나의 동기식 렌더링으로 유지하세요.
Redis 구성에도 불구하고 서버가 인메모리로 폴백됨. REST 서버는 부팅 시 Redis 연결에 실패하면 자동으로 폴백됩니다. Redis에 접근할 수 있는지 확인하고 실행 중인 이미지에 ext-redis가 있는지도 확인하세요. 확인하지 않은 채 Redis가 사용되고 있다고 가정하지 마세요.
서버가 구성 오류로 부팅을 거부함. risk_level_overrides 항목이 ApprovalRequired 도구를 다운그레이드하려고 했습니다. 로더는 설계상 이를 거부합니다. 다운그레이드를 제거하세요. 오버라이드는 위험도를 높일 때만 가능합니다.

성능

부하 상태에서 렌더링이 느리다면 워커 풀이 포화되지 않았는지 확인하세요. RoadRunner 메트릭 엔드포인트를 확인하세요. 그런 다음 워커가 점유되지 않도록 장시간 렌더링을 비동기 작업 경로로 옮기세요. 자세한 내용은 /connect/production-usage/를 참고하세요.

보안 참고 사항

인증되지 않은 MCP 전송 계층을 네트워크에 노출하는 방식으로 401을 우회하지 마세요. 그렇게 하면 인증이 완전히 제거됩니다. 대신 API 키를 수정하세요. 공유 환경에서는 도구 인수를 검사하려고 로그 상세도를 높이지 마세요. 인수 페이로드에는 민감한 정보가 포함될 수 있습니다. 자세한 내용은 /connect/security-and-operations/를 참고하세요.

적합성

이 페이지는 운영 지침입니다. 프로토콜 및 보안 관련 인용은 /transports/mcp/, /transports/rest/, /connect/security-and-operations/에 고정되어 있습니다.

참고 항목

/connect/tool-catalog/ — 코어 카탈로그에 포함된 항목과 개수가 달라지는 이유
/connect/hitl-risk-tiers/ — 확인 챌린지에 대한 자세한 설명
/connect/deployment/ — Redis, 워커 풀, 스토어 공유
/connect/security-and-operations/ — 인증 실패 및 보안 태세