從僅支援 MCP 遷移至多重傳輸（multi-transport）

概覽

將整合從 MCP stdio 傳輸遷移到 REST 或 gRPC 傳輸。引擎行為不會改變；工具目錄、風險模型，以及確認 gate（閘門）都會完全一致。會改變的只有三件事：wire 協定、驗證方式，以及並行模型。

安裝

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

概念總覽

本套件早期的文件只描述單一傳輸：透過 stdio 的 MCP。現在本套件會透過三種傳輸提供同一份工具註冊表（tool registry）。遷移包含兩個步驟：先挑選一種網路傳輸，再把 MCP 呼叫對映到該傳輸。它不會要求你重寫文件邏輯。

請依你的部署型態選擇合適的傳輸：

維持使用 MCP：適用於單一本機 AI Agent（代理）、需要最低延遲（沒有網路跳轉），或使用 MCP 原生用戶端（例如本機 IDE 助手）的情境。
改用 REST：適用於需要多用戶端存取、為每個用戶端配置 API key、在容器或 Kubernetes 中部署、針對每個用戶端限流、使用非同步工作（async job），或以任意語言撰寫用戶端的情境。
改用 gRPC：適用於需要具型別合約、以伺服器串流（server-streaming）傳輸大型 PDF，以及採用雙向 TLS（mutual-TLS）的服務對服務部署。

API 介面

哪些維持不變

工具註冊表，以及依執行環境決定的工具目錄（詳見 /connect/tool-catalog/ 一節）。
四級風險模型，以及確認 gate（詳見 /connect/hitl-risk-tiers/ 一節）。
文件模型與引擎語意。

哪些會改變

面向	MCP（stdio 標準輸入輸出）	REST	gRPC
Wire 格式	透過 stdio 的 JSON-RPC 2.0	透過 HTTP 的 JSON	透過 gRPC 的 Protobuf
驗證	無（本機子行程）	`Authorization: Bearer` API key（API 金鑰）	在呼叫中繼資料（call metadata）中帶 bearer
並行	單一行程，一次一個呼叫	RoadRunner worker 池	RoadRunner gRPC 池
非同步	不適用	工作 endpoint（端點）	工作 RPC
串流	不適用	同步回應主體	伺服器串流 RPC

概念對映

典型的 MCP 序列會先 create_pdf，接著呼叫內容工具，最後呼叫 output_pdf。在 REST 上，這會收斂為單一無狀態的 POST /api/v1/render，並附上一個有順序的 operations 陣列。需要逐步累積狀態時，請改用選用的 session endpoint。在 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`（加上 session 操作）	`CreateSession`（加上 `SessionOperation`）
長時間算繪	`POST /api/v1/jobs` 然後輪詢結果	`SubmitJob` 然後 `GetJobResult`
受分級控管（tier-gated）的操作	`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 設定檔（profile）會由同一個 supervisor 同時提供 REST 與 gRPC。舊的 MCP 整合可在仍然合適的地方繼續於本機執行：

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

沒有需要遷移的共用狀態。這些傳輸是在同一個引擎之上彼此獨立的行程。請逐步把用戶端切換過去。

邊界情況與陷阱

加上驗證。 MCP 傳輸原本沒有驗證，因為它是本機子行程。網路傳輸要求每個非健康檢查（health）請求都帶有效的 API key。切換前請先配置好 key。請見 /connect/security-and-operations/.
確認 gate 仍會觸發。 一個 approval_required 工具在 REST 與 gRPC 上發出的挑戰，與它在 MCP 上的行為完全相同。請把確認流程納入新的整合。不要以為這個 gate 只存在於 MCP。請見 /connect/hitl-risk-tiers/.
分級控管維持不變。 一個 Pro 或 Enterprise 操作在新傳輸上一樣需要已安裝 nextpdf/premium 並持有具權限的 key，就和對應工具在 MCP 上需要該套件一樣。
冪等性（idempotency）是新增且實用的功能。 REST 加入了 stdio 傳輸從未提供的冪等性控制。用它讓工作提交可以安全地重試。請見 /connect/production-usage/.

效能

MCP 是單一行程，對單一本機代理而言延遲最低。網路傳輸會多出一個 worker 池與一次網路跳轉。作為交換，它們可以擴展到大量並行用戶端。請把長時間算繪改走新傳輸上的非同步工作路徑，避免 worker 被佔住。

安全性注意事項

從 stdio 遷移出去，代表你開始承擔網路曝險。請在 REST 前端終結 TLS，在不可信任的網路上對 gRPC 採用雙向 TLS，為每個用戶端限縮 key 範圍，並把 enabled_tools 維持在最小範圍。MCP 傳輸不需憑證的模型之所以安全，只是因為它是本機子行程。不要在網路上重現那種曝險。請見 /connect/security-and-operations/.

符合性

本頁是遷移指引。協定與驗證的引用來源，分別固定於 /transports/mcp/、/transports/rest/、/transports/grpc/ 與 /connect/security-and-operations/.

商業脈絡

受分級控管的操作不論使用哪一種傳輸，都需要 nextpdf/premium。遷移不會改變哪些屬於 core、哪些屬於 Premium；它只會改變工具目錄的存取方式。

另請參閱

/transports/mcp/ — 你要遷移離開的傳輸
/transports/rest/ · /transports/grpc/ — 你要遷移過去的傳輸
/connect/tool-catalog/ — 跨各傳輸都一致的工具目錄
/connect/hitl-risk-tiers/ — 跨各傳輸都一致的確認 gate
/connect/security-and-operations/ — 你必須加上的驗證