Migrating from MCP-only to multi-transport

At a glance

Move an integration from the Model Context Protocol (MCP) stdio transport to Representational State Transfer (REST) or gRPC. Engine behavior does not change. The catalog, risk model, and confirmation gate stay the same. Three things change: wire protocol, authentication, and concurrency model.

Install

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

Conceptual overview

Early documentation for this package described one transport: MCP over stdio. The package now serves the same tool registry over three transports. To migrate, choose a networked transport, then map your MCP calls to it. You do not need to rewrite your document logic.

Choose the transport that fits your deployment:

Stay on MCP for a single local agent, the lowest latency (no network hop), or an MCP-native client, such as a local IDE assistant.
Move to REST for multi-client access with per-client API keys, container or Kubernetes deployment, per-client rate limiting, async jobs, or clients in any language.
Move to gRPC for typed contracts, server-streaming large PDFs, and mutual-TLS service-to-service deployments.

API surface

What stays the same

The tool registry and the runtime-dependent catalog (see /connect/tool-catalog/).
The four-level risk model and the confirmation gate (see /connect/hitl-risk-tiers/).
The document model and engine semantics.

What changes

Aspect	MCP (stdio)	REST	gRPC
Wire format	JSON-RPC 2.0 over stdio	JSON over HTTP	Protobuf over gRPC
Authentication	none (local subprocess)	`Authorization: Bearer` API key	bearer in call metadata
Concurrency	one process, one call	RoadRunner worker pool	RoadRunner gRPC pool
Async	not applicable	job endpoints	job RPCs
Streaming	not applicable	sync body	server-streaming RPCs

Concept mapping

A typical MCP sequence is create_pdf, then content tools, then output_pdf. In REST, this becomes one stateless POST /api/v1/render request with an ordered operations array. When you need step-by-step state, use the opt-in session endpoints instead. In gRPC, the equivalent is the Render RPC, or RenderStream for chunked delivery. For stateful builds, use the CreateSession, SessionOperation, and SessionRender RPCs.

MCP tool sequence	REST	gRPC
`create_pdf` + content tools + `output_pdf`	`POST /api/v1/render`	`Render` / `RenderStream`
Stateful build across calls	`POST /api/v1/sessions` (+ session ops)	`CreateSession` (+ `SessionOperation`)
Long render	`POST /api/v1/jobs` then poll result	`SubmitJob` then `GetJobResult`
Tier-gated operation	`POST /api/v1/<operation>`	`ExecuteCapability`

Code sample — Quick start

The MCP call:

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

becomes the REST request:

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

Code sample — Production

Run both transports during a phased migration. The combined RoadRunner profile serves REST and gRPC from one supervisor. The old MCP integration can keep running locally where it still fits:

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

There is no shared state to migrate. The transports are independent processes over the same engine. Move clients over incrementally.

Edge cases and gotchas

Add authentication. The MCP transport had none because it was a local subprocess. The networked transports require a valid API key on every non-health request. Provision keys before cutover. See /connect/security-and-operations/.
The confirmation gate still fires. An approval_required tool challenges in REST and gRPC exactly as it did in MCP. Carry the confirmation flow into the new integration. Do not assume the gate is MCP-only. See /connect/hitl-risk-tiers/.
Tier gating is unchanged. A Pro or Enterprise operation needs nextpdf/premium installed and an entitled key on the new transport, just as the corresponding tool needed the package in MCP.
Idempotency is new and useful. REST adds an idempotency control that the stdio transport never had. Use it to make job submission safe to retry. See /connect/production-usage/.

Performance

MCP is single-process and has the lowest latency for one local agent. The networked transports add a worker pool and a network hop. In return, they scale to many concurrent clients. Move long renders to the async job path on the new transport so workers are not held.

Security notes

Migrating off stdio adds network exposure. Terminate Transport Layer Security (TLS) in front of REST, use mutual TLS for gRPC on untrusted networks, scope keys per client, and keep enabled_tools minimal. The MCP transport’s no-credential model is safe only because it is a local subprocess. Do not recreate that exposure over a network. See /connect/security-and-operations/.

Conformance

This page provides migration guidance. Protocol and authentication citations are pinned on /transports/mcp/, /transports/rest/, /transports/grpc/, and /connect/security-and-operations/.

Commercial context

Tier-gated operations require nextpdf/premium regardless of transport. Migrating does not change what is core versus Premium. It changes only how you reach the catalog.