Migrer d'une intégration MCP seule vers le multi-transport

En bref

Fais évoluer une intégration qui utilise le transport stdio de MCP vers le transport REST ou gRPC. Le comportement du moteur ne change pas. Le catalogue, le modèle de risque et la porte de confirmation restent identiques. Trois éléments changent : le protocole de transmission, l’authentification et le modèle de concurrence.

Installation

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

Vue d’ensemble conceptuelle

La documentation initiale de ce package décrivait un transport unique : MCP sur stdio. Le package expose désormais le même registre d’outils sur trois transports. La migration se fait en deux étapes : choisir un transport réseau, puis y faire correspondre les appels MCP. Elle ne t’oblige pas à réécrire la logique de tes documents.

Choisis le transport qui correspond à la forme de ton déploiement :

Reste sur MCP pour un seul agent local, la latence la plus faible (aucun saut réseau) ou un client natif MCP (par exemple un assistant d’IDE local).
Passe à REST pour un accès multi-client avec des clés d’API par client, un déploiement en conteneur ou sur Kubernetes, une limitation de débit par client, des jobs asynchrones ou des clients écrits dans n’importe quel langage.
Passe à gRPC pour des contrats typés, le streaming serveur de gros PDF et des déploiements service-à-service en TLS mutuel.

Surface d’API

Ce qui reste inchangé

Le registre d’outils et le catalogue dépendant de l’exécution (voir /connect/tool-catalog/).
Le modèle de risque à quatre niveaux et la porte de confirmation (voir /connect/hitl-risk-tiers/).
Le modèle de document et la sémantique du moteur.

Ce qui change

Aspect	MCP (stdio)	REST	gRPC
Format de transmission	JSON-RPC 2.0 sur stdio	JSON sur HTTP	Protobuf sur gRPC
Authentification	aucune (sous-processus local)	`Authorization: Bearer` clé d’API	bearer dans les métadonnées de l’appel
Concurrence	un processus, un appel	pool de workers RoadRunner	pool gRPC RoadRunner
Asynchrone	non applicable	endpoints de jobs	RPC de jobs
Streaming	non applicable	corps synchrone	RPC de streaming serveur

Correspondance des concepts

Une séquence MCP typique enchaîne create_pdf, les outils de contenu, puis output_pdf. Sur REST, elle se traduit par un seul POST /api/v1/render sans état avec un tableau operations ordonné. Si tu as besoin de conserver un état étape par étape, utilise plutôt les endpoints de session optionnels. Sur gRPC, l’équivalent est le RPC Render, ou RenderStream pour une livraison par fragments. Pour les constructions avec état, utilise les RPC CreateSession, SessionOperation et SessionRender.

Séquence d’outils MCP	REST	gRPC
`create_pdf` + outils de contenu + `output_pdf`	`POST /api/v1/render`	`Render` / `RenderStream`
Construction avec état sur plusieurs appels	`POST /api/v1/sessions` (+ opérations de session)	`CreateSession` (+ `SessionOperation`)
Rendu long	`POST /api/v1/jobs` puis interroger le résultat	`SubmitJob` puis `GetJobResult`
Opération contrôlée par le niveau	`POST /api/v1/<operation>`	`ExecuteCapability`

Exemple de code — Démarrage rapide

L’appel MCP :

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

devient la requête 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

Exemple de code — Production

Fais tourner les deux transports pendant une migration progressive. Le profil RoadRunner combiné expose REST et gRPC depuis un seul superviseur. L’ancienne intégration MCP continue de tourner localement là où elle convient encore :

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

Aucun état partagé n’est à migrer. Les transports sont des processus indépendants au-dessus du même moteur. Bascule les clients progressivement.

Cas limites et pièges

Ajoute l’authentification. Le transport MCP n’en avait aucune parce qu’il s’agit d’un sous-processus local. Les transports réseau exigent une clé d’API valide sur chaque requête, sauf celles de health. Provisionne les clés avant la bascule. Voir /connect/security-and-operations/.
La porte de confirmation se déclenche toujours. Un outil approval_required demande une confirmation sur REST et gRPC exactement comme il le faisait sur MCP. Intègre le flux de confirmation dans la nouvelle intégration. Ne suppose pas que la porte est propre à MCP. Voir /connect/hitl-risk-tiers/.
Le contrôle par niveau est inchangé. Une opération Pro ou Enterprise nécessite que nextpdf/premium soit installé et qu’une clé habilitée soit utilisée sur le nouveau transport, exactement comme l’outil correspondant nécessitait le package sur MCP.
L’idempotence est une nouveauté utile. REST ajoute un contrôle d’idempotence que le transport stdio n’a jamais eu. Sers-t’en pour rendre la soumission de job sûre en cas de nouvelle tentative. Voir /connect/production-usage/.

Performances

MCP est mono-processus et offre la latence la plus faible pour un seul agent local. Les transports réseau ajoutent un pool de workers et un saut réseau. En contrepartie, ils montent en charge pour de nombreux clients concurrents. Déplace les rendus longs vers le chemin de job asynchrone sur le nouveau transport afin de ne pas monopoliser les workers.

Notes de sécurité

Migrer hors de stdio revient à assumer une exposition réseau. Termine TLS en amont de REST, utilise le TLS mutuel pour gRPC sur les réseaux non fiables, restreins la portée des clés par client et garde enabled_tools minimal. Le modèle sans identifiant du transport MCP n’est sûr que parce qu’il s’agit d’un sous-processus local. Ne recrée pas cette exposition sur un réseau. Voir /connect/security-and-operations/.

Conformité

Cette page est un guide de migration. Les citations relatives au protocole et à l’authentification s’appuient sur /transports/mcp/, /transports/rest/, /transports/grpc/ et /connect/security-and-operations/.

Contexte commercial

Les opérations contrôlées par le niveau nécessitent nextpdf/premium quel que soit le transport. Migrer ne change pas ce qui relève du cœur ou de Premium. Cela change seulement la façon d’accéder au catalogue.

Voir aussi

/transports/mcp/ — le transport depuis lequel tu migres
/transports/rest/ · /transports/grpc/ — les transports vers lesquels tu migres
/connect/tool-catalog/ — le catalogue, identique d’un transport à l’autre
/connect/hitl-risk-tiers/ — la porte, identique d’un transport à l’autre
/connect/security-and-operations/ — l’authentification que tu dois ajouter