MCP 전용 구성에서 다중 전송으로 마이그레이션

한눈에 보기

통합을 MCP stdio 전송에서 REST 또는 gRPC 전송으로 옮깁니다. 엔진 동작은 바뀌지 않습니다. 카탈로그, 위험 모델, 확인 게이트는 동일하게 유지됩니다. 달라지는 것은 와이어 프로토콜, 인증, 동시성 모델 세 가지입니다.

설치

composer require nextpdf/server
./vendor/bin/rr get-binary

개념 개요

이 패키지의 초기 문서는 stdio 기반 MCP라는 단일 전송만 설명했습니다. 이제 이 패키지는 동일한 도구 레지스트리를 세 가지 전송으로 제공합니다. 마이그레이션은 두 단계로 진행됩니다. 먼저 네트워크 전송을 선택한 뒤, MCP 호출을 그 전송 위에 매핑합니다. 문서 로직을 다시 작성하는 작업은 아닙니다.

배포 형태에 맞는 전송을 선택하십시오.

MCP를 유지하십시오. 단일 로컬 에이전트, 가장 낮은 지연 시간(네트워크 홉 없음) 또는 MCP 네이티브 클라이언트(예: 로컬 IDE 어시스턴트)에 적합합니다.
REST로 이동하십시오. 클라이언트별 API 키를 사용하는 다중 클라이언트 액세스, 컨테이너 또는 Kubernetes 배포, 클라이언트별 속도 제한, 비동기 작업 또는 임의 언어로 작성된 클라이언트에 적합합니다.
gRPC로 이동하십시오. 타입이 지정된 계약, 대용량 PDF의 서버 스트리밍, 상호 TLS 기반 서비스 간 배포에 적합합니다.

API 표면

동일하게 유지되는 것

도구 레지스트리와 런타임에 따라 달라지는 카탈로그(/connect/tool-catalog/ 참조).
4단계 위험 모델과 확인 게이트(/connect/hitl-risk-tiers/ 참조).
문서 모델과 엔진 의미 체계.

변경되는 것

항목	MCP (stdio) 전송	REST	gRPC
와이어 형식	stdio 기반 JSON-RPC 2.0	HTTP 기반 JSON	gRPC 기반 Protobuf
인증	없음(로컬 하위 프로세스)	`Authorization: Bearer` API 키	호출 메타데이터의 bearer
동시성	프로세스 1개, 호출 1개	RoadRunner 워커 풀	RoadRunner gRPC 풀
비동기	해당 없음	작업 엔드포인트	작업 RPC
스트리밍	해당 없음	동기 본문	서버 스트리밍 RPC

개념 매핑

일반적인 MCP 시퀀스는 create_pdf, 콘텐츠 도구, output_pdf 순서입니다. REST에서는 이를 순서가 지정된 operations 배열을 사용하는 단일 무상태 POST /api/v1/render로 통합합니다. 단계별 상태가 필요한 경우, 대신 옵트인 세션 엔드포인트를 사용하십시오. gRPC에서 이에 해당하는 것은 Render RPC이며, 청크 단위 전달에는 RenderStream을 사용합니다. 상태 저장 빌드의 경우 CreateSession, SessionOperation, SessionRender RPC를 사용하십시오.

MCP 도구 시퀀스	REST	gRPC
`create_pdf` + 콘텐츠 도구 + `output_pdf`	`POST /api/v1/render`	`Render` / `RenderStream`
호출 간 상태 저장 빌드	`POST /api/v1/sessions` (+ 세션 작업)	`CreateSession` (+ `SessionOperation`)
긴 렌더링	`POST /api/v1/jobs` 후 결과 폴링	`SubmitJob` 후 `GetJobResult`
계층 게이트 작업	`POST /api/v1/<operation>`	`ExecuteCapability`

코드 샘플 — 빠른 시작

MCP 호출:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_text","arguments":{"text":"Hello"}}}

위 호출은 다음 REST 요청으로 바뀝니다.

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

코드 샘플 — 프로덕션

단계적으로 마이그레이션하는 동안에는 두 전송을 모두 실행하십시오. 통합 RoadRunner 프로필은 하나의 슈퍼바이저에서 REST와 gRPC를 제공합니다. 기존 MCP 통합도 여전히 적합한 로컬 환경에서 계속 실행할 수 있습니다.

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

마이그레이션할 공유 상태는 없습니다. 각 전송은 동일한 엔진 위에서 동작하는 독립 프로세스입니다. 클라이언트를 점진적으로 전환하십시오.

엣지 케이스와 주의 사항

인증을 추가하십시오. MCP 전송은 로컬 하위 프로세스이므로 인증이 없었습니다. 네트워크 전송은 health를 제외한 모든 요청에 유효한 API 키를 요구합니다. 전환 전에 키를 프로비저닝하십시오. /connect/security-and-operations/. 참조
확인 게이트는 여전히 발동합니다. approval_required 도구는 MCP에서와 정확히 동일하게 REST와 gRPC에서도 확인을 요구합니다. 확인 흐름을 새 통합에도 이어 가십시오. 게이트가 MCP 전용이라고 가정해서는 안 됩니다. /connect/hitl-risk-tiers/. 참조
계층 게이트는 변경되지 않습니다. Pro 또는 Enterprise 작업은 해당 도구가 MCP에서 패키지를 요구했던 것과 정확히 마찬가지로, 새 전송에서도 nextpdf/premium 설치와 권한이 부여된 키가 필요합니다.
멱등성은 새롭고 유용합니다. REST는 stdio 전송에는 없었던 멱등성 제어를 추가합니다. 이를 사용하여 작업 제출을 안전하게 재시도할 수 있도록 하십시오. /connect/production-usage/. 참조

성능

MCP는 단일 프로세스이며 단일 로컬 에이전트에 대해 가장 낮은 지연 시간을 제공합니다. 네트워크 전송은 워커 풀과 네트워크 홉을 추가하지만, 다수의 동시 클라이언트로 확장할 수 있습니다. 긴 렌더링은 워커를 점유하지 않도록 새 전송의 비동기 작업 경로로 옮기십시오.

보안 참고 사항

stdio에서 마이그레이션한다는 것은 네트워크 노출을 감수한다는 의미입니다. REST 앞단에서 TLS를 종료하고, 신뢰할 수 없는 네트워크의 gRPC에는 상호 TLS를 사용하며, 키 범위를 클라이언트별로 한정하고, enabled_tools를 최소한으로 유지하십시오. MCP 전송의 자격 증명 없는 모델은 로컬 하위 프로세스일 때만 안전합니다. 같은 노출을 네트워크에서 재현하지 마십시오. /connect/security-and-operations/. 참조

적합성

이 페이지는 마이그레이션 안내입니다. 프로토콜 및 인증 관련 인용은 /transports/mcp/, /transports/rest/, /transports/grpc/, /connect/security-and-operations/.에 고정되어 있습니다.

상용 컨텍스트

계층 게이트 작업은 전송과 관계없이 nextpdf/premium을 필요로 합니다. 마이그레이션은 무엇이 코어이고 무엇이 Premium인지를 바꾸지 않습니다. 카탈로그에 접근하는 방식만 바뀝니다.