Migreren van MCP-only naar multi-transport

In een oogopslag

Migreer een integratie van het stdio-transport van het Model Context Protocol (MCP) naar Representational State Transfer (REST) of gRPC. Het gedrag van de engine verandert niet. De catalogus, het risicomodel en de bevestigingspoort blijven hetzelfde. Er veranderen drie zaken: het wire protocol, de authenticatie en het concurrency-model.

Installeren

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

Conceptueel overzicht

De vroege documentatie voor dit pakket beschreef één transport: MCP via stdio. Het pakket biedt nu hetzelfde tool-register via drie transports. Kies voor de migratie een netwerktransport en zet daarna je MCP-aanroepen daarop over. Je hoeft je documentlogica niet te herschrijven.

Kies het transport dat bij je deployment past:

Blijf bij MCP als je één lokale agent gebruikt, de laagste latentie nodig hebt (geen netwerkhop) of een MCP-native client hebt, zoals een lokale IDE-assistent.
Stap over op REST voor toegang door meerdere clients met API-sleutels per client, container- of Kubernetes-deployment, rate limiting per client, asynchrone taken of clients in elke taal.
Stap over op gRPC voor getypeerde contracten, server-streaming van grote PDF-bestanden en service-to-service-deployments met mutual TLS.

API-oppervlak

Wat hetzelfde blijft

Het tool-register en de runtime-afhankelijke catalogus (zie /connect/tool-catalog/).
Het risicomodel met vier niveaus en de bevestigingspoort (zie /connect/hitl-risk-niveaus/).
Het documentmodel en de engine-semantiek.

Wat verandert

Aspect	MCP (stdio)	REST	gRPC
Wire-formaat	JSON-RPC 2.0 via stdio	JSON via HTTP	Protobuf via gRPC
Authenticatie	geen (lokaal subproces)	`Authorization: Bearer`-API-sleutel	bearer in call metadata
Concurrency	één proces, één aanroep	RoadRunner-workerpool	RoadRunner gRPC-pool
Async	niet van toepassing	job-endpoints	job-RPC’s
Streaming	niet van toepassing	synchrone body	server-streaming RPC’s

Conceptkoppeling

Een typische MCP-volgorde is create_pdf, daarna content-tools en vervolgens output_pdf. In REST wordt dit één stateless POST /api/v1/render-verzoek met een geordende operations-array. Als je stapsgewijze status nodig hebt, gebruik je in plaats daarvan de opt-in session-endpoints. In gRPC is de tegenhanger de Render-RPC, of RenderStream voor levering in chunks. Gebruik voor stateful builds de RPC’s CreateSession, SessionOperation en SessionRender.

MCP-toolvolgorde	REST	gRPC
`create_pdf` + content-tools + `output_pdf`	`POST /api/v1/render`	`Render` / `RenderStream`
Stateful build over meerdere aanroepen	`POST /api/v1/sessions` (+ session-ops)	`CreateSession` (+ `SessionOperation`)
Lange render	`POST /api/v1/jobs` en vervolgens het resultaat pollen	`SubmitJob` en vervolgens `GetJobResult`
Tier-gated bewerking	`POST /api/v1/<operation>`	`ExecuteCapability`

Codevoorbeeld — Snelstart

De MCP-aanroep:

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

wordt dit REST-verzoek:

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

Codevoorbeeld — Productie

Voer tijdens een gefaseerde migratie beide transports naast elkaar uit. Het gecombineerde RoadRunner-profiel biedt REST en gRPC vanuit één supervisor. De oude MCP-integratie kan lokaal blijven draaien waar dat nog past:

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

Er is geen gedeelde status die je moet migreren. De transports zijn onafhankelijke processen bovenop dezelfde engine. Zet clients stapsgewijs over.

Randgevallen en valkuilen

Voeg authenticatie toe. Het MCP-transport had geen authenticatie, omdat het een lokaal subproces was. De netwerktransports vereisen een geldige API-sleutel bij elk verzoek dat geen health-verzoek is. Stel de sleutels in vóór de overstap. Zie /connect/security-and-operations/.
De bevestigingspoort treedt nog steeds in werking. Een approval_required-tool geeft in REST en gRPC precies dezelfde challenge als in MCP. Neem de bevestigingsflow mee in de nieuwe integratie. Ga er niet van uit dat de poort alleen voor MCP geldt. Zie /connect/hitl-risk-niveaus/.
Tier gating is ongewijzigd. Een Pro- of Enterprise-bewerking vereist dat nextpdf/premium is geïnstalleerd en dat op het nieuwe transport een bevoegde sleutel beschikbaar is, net zoals de bijbehorende tool het pakket in MCP nodig had.
Idempotentie is nieuw en nuttig. REST voegt idempotency control toe die het stdio-transport nooit had. Gebruik dit om het indienen van taken veilig opnieuw te kunnen proberen. Zie /connect/production-usage/.

Prestaties

MCP draait in één proces en heeft de laagste latentie voor één lokale agent. De netwerktransports voegen een workerpool en een netwerkhop toe. Daar staat tegenover dat ze schalen naar veel gelijktijdige clients. Verplaats lange renders naar het asynchrone job-pad op het nieuwe transport, zodat workers niet bezet blijven.

Beveiligingsnotities

Migreren vanaf stdio voegt netwerkblootstelling toe. Zorg dat Transport Layer Security (TLS) vóór REST wordt beëindigd, gebruik mutual TLS voor gRPC op niet-vertrouwde netwerken, beperk sleutels per client en houd enabled_tools minimaal. Het model zonder inloggegevens van het MCP-transport is alleen veilig omdat het een lokaal subproces is. Creëer die blootstelling niet opnieuw via een netwerk. Zie /connect/security-and-operations/.

Conformiteit

Deze pagina biedt migratierichtlijnen. Citaten over protocol en authenticatie zijn vastgelegd op /transports/mcp/, /transports/rest/, /transports/grpc/ en /connect/security-and-operations/.

Commerciële context

Tier-gated bewerkingen vereisen nextpdf/premium, ongeacht het transport. Migreren verandert niet wat onder core valt en wat onder Premium valt. Het verandert alleen hoe je de catalogus bereikt.

Zie ook

/transports/mcp/ — het transport waarvandaan je migreert
/transports/rest/ · /transports/grpc/ — de transports waarnaar je migreert
/connect/tool-catalog/ — de catalogus, identiek voor alle transports
/connect/hitl-risk-niveaus/ — de bevestigingspoort, identiek voor alle transports
/connect/security-and-operations/ — de authenticatie die je moet toevoegen