Di chuyển từ chế độ chỉ dùng MCP sang nhiều giao thức

Tổng quan nhanh

Chuyển một tích hợp từ Model Context Protocol (MCP) qua stdio sang Representational State Transfer (REST) hoặc gRPC. Hành vi của engine không thay đổi. Danh mục, mô hình rủi ro và cổng xác nhận vẫn giữ nguyên. Ba yếu tố thay đổi là giao thức truyền, xác thực và mô hình đồng thời.

Cài đặt

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

Tổng quan khái niệm

Tài liệu ban đầu của gói này mô tả một giao thức: MCP qua stdio. Giờ đây, gói này cung cấp cùng một tool registry qua ba giao thức. Để di chuyển, hãy chọn một giao thức qua mạng, rồi ánh xạ các lệnh gọi MCP của bạn sang giao thức đó. Bạn không cần viết lại logic xử lý tài liệu của mình.

Chọn giao thức phù hợp với phương án triển khai của bạn:

Giữ MCP khi bạn có một agent cục bộ duy nhất, cần độ trễ thấp nhất (không có bước nhảy qua mạng), hoặc dùng một client MCP-native, chẳng hạn như trợ lý IDE cục bộ.
Chuyển sang REST khi cần nhiều client truy cập với khóa API riêng cho từng client, triển khai bằng container hoặc Kubernetes, giới hạn tốc độ theo từng client, job bất đồng bộ, hoặc client viết bằng bất kỳ ngôn ngữ nào.
Chuyển sang gRPC khi cần hợp đồng được định kiểu, truyền PDF lớn theo kiểu server-streaming, và triển khai giữa dịch vụ với dịch vụ bằng mutual-TLS.

Bề mặt API

Những gì giữ nguyên

Tool registry và danh mục phụ thuộc runtime (xem /connect/tool-catalog/).
Mô hình rủi ro bốn cấp và cổng xác nhận (xem /connect/hitl-risk-tiers/).
Mô hình tài liệu và ngữ nghĩa của engine.

Những gì thay đổi

Khía cạnh	MCP (stdio)	REST	gRPC
Định dạng truyền	JSON-RPC 2.0 qua stdio	JSON qua HTTP	Protobuf qua gRPC
Xác thực	không có (tiến trình con cục bộ)	`Authorization: Bearer` khóa API	bearer trong metadata của lệnh gọi
Đồng thời	một tiến trình, một lệnh gọi	nhóm worker RoadRunner	nhóm gRPC RoadRunner
Bất đồng bộ	không áp dụng	các endpoint job	các RPC job
Truyền luồng	không áp dụng	phần thân đồng bộ	các RPC server-streaming

Ánh xạ khái niệm

Một chuỗi MCP điển hình gồm create_pdf, các công cụ nội dung, rồi output_pdf. Trong REST, chuỗi này trở thành một yêu cầu POST /api/v1/render không trạng thái với một mảng operations theo thứ tự. Khi cần trạng thái theo từng bước, hãy dùng các endpoint session opt-in thay thế. Trong gRPC, phần tương đương là RPC Render, hoặc RenderStream để phân phối theo từng phần. Với các bản dựng có trạng thái, hãy dùng các RPC CreateSession, SessionOperation và SessionRender.

Chuỗi công cụ MCP	REST	gRPC
`create_pdf` + các công cụ nội dung + `output_pdf`	`POST /api/v1/render`	`Render` / `RenderStream`
Bản dựng có trạng thái qua nhiều lệnh gọi	`POST /api/v1/sessions` (+ các thao tác session)	`CreateSession` (+ `SessionOperation`)
Kết xuất kéo dài	`POST /api/v1/jobs` rồi thăm dò kết quả	`SubmitJob` rồi `GetJobResult`
Thao tác bị kiểm soát theo cấp	`POST /api/v1/<operation>`	`ExecuteCapability`

Mẫu mã — bắt đầu nhanh

Lệnh gọi MCP:

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

trở thành yêu cầu 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

Mẫu mã — sản xuất

Chạy cả hai giao thức trong quá trình di chuyển theo từng giai đoạn. Hồ sơ RoadRunner kết hợp phục vụ cả REST và gRPC từ một supervisor duy nhất. Tích hợp MCP cũ vẫn có thể tiếp tục chạy cục bộ ở nơi vẫn phù hợp:

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

Không có trạng thái dùng chung nào cần di chuyển. Các giao thức là những tiến trình độc lập chạy trên cùng một engine. Hãy chuyển dần các client sang giao thức mới.

Trường hợp đặc biệt và điểm cần lưu ý

Thêm xác thực. Giao thức MCP không có xác thực nào vì nó là một tiến trình con cục bộ. Các giao thức qua mạng yêu cầu một khóa API hợp lệ cho mọi yêu cầu không dùng để kiểm tra tình trạng. Hãy chuẩn bị sẵn khóa trước khi chuyển đổi. Xem /connect/security-and-operations/.
Cổng xác nhận vẫn được kích hoạt. Một công cụ approval_required sẽ yêu cầu xác nhận trong REST và gRPC giống hệt như trong MCP. Hãy chuyển cả luồng xác nhận sang tích hợp mới. Đừng cho rằng cổng này chỉ dành cho MCP. Xem /connect/hitl-risk-tiers/.
Việc kiểm soát theo cấp không thay đổi. Một thao tác Pro hoặc Enterprise cần cài đặt nextpdf/premium và một khóa có quyền tương ứng trên giao thức mới, giống như công cụ tương ứng cần gói này trong MCP.
Idempotency là điểm mới và hữu ích. REST bổ sung một cơ chế kiểm soát idempotency mà giao thức stdio chưa từng có. Hãy dùng cơ chế này để việc gửi job có thể thử lại một cách an toàn. Xem /connect/production-usage/.

Hiệu năng

MCP chạy trong một tiến trình và có độ trễ thấp nhất cho một agent cục bộ. Các giao thức qua mạng bổ sung thêm một nhóm worker và một bước nhảy qua mạng. Đổi lại, chúng có thể mở rộng cho nhiều client đồng thời. Hãy chuyển các tác vụ kết xuất kéo dài sang luồng job bất đồng bộ trên giao thức mới để worker không bị chiếm giữ.

Lưu ý bảo mật

Việc rời khỏi stdio làm tăng bề mặt phơi nhiễm mạng. Hãy kết thúc Transport Layer Security (TLS) ở phía trước REST, dùng mutual TLS cho gRPC trên các mạng không tin cậy, giới hạn phạm vi khóa theo từng client, và giữ enabled_tools ở mức tối thiểu. Mô hình không có thông tin xác thực của giao thức MCP chỉ an toàn vì nó là một tiến trình con cục bộ. Đừng tái tạo mức phơi nhiễm đó qua mạng. Xem /connect/security-and-operations/.

Tuân thủ

Trang này cung cấp hướng dẫn di chuyển. Các trích dẫn về giao thức và xác thực được đặt tại /transports/mcp/, /transports/rest/, /transports/grpc/, và /connect/security-and-operations/.

Bối cảnh thương mại

Các thao tác bị kiểm soát theo cấp đều cần nextpdf/premium bất kể giao thức nào. Việc di chuyển không thay đổi phần nào là core và phần nào là Premium. Nó chỉ thay đổi cách bạn truy cập danh mục.

Xem thêm

/transports/mcp/ — giao thức bạn rời khỏi
/transports/rest/ · /transports/grpc/ — các giao thức bạn chuyển sang
/connect/tool-catalog/ — danh mục, giống nhau trên mọi giao thức
/connect/hitl-risk-tiers/ — cổng xác nhận, giống nhau trên mọi giao thức
/connect/security-and-operations/ — phần xác thực bạn phải thêm vào