Transport MCP de NextPDF Connect

En bref

Le transport MCP exécute bin/nextpdf-mcp comme sous-processus local. Il communique en JSON-RPC 2.0 via l’entrée et la sortie standard. Le serveur implémente la révision du protocole MCP datée 2025-06-18.

Installation

composer require nextpdf/server

Vue d’ensemble conceptuelle

Dans le modèle stdio de MCP, le client lance le serveur comme sous-processus. Le client échange des messages JSON-RPC séparés par des sauts de ligne : un message par ligne, sans saut de ligne interne, en UTF-8. Le serveur n’écrit que des messages MCP valides sur la sortie standard et réserve la sortie d’erreur standard à la journalisation. L’implémentation achemine son journal d’audit vers la sortie d’erreur standard précisément pour que les lignes de log ne corrompent jamais le flux du protocole. Ce cadrage est défini par la spécification officielle de MCP, révision 2025-06-18. Cette spécification ne fait pas partie du corpus de normes sous licence ; elle est donc citée par son URL : https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect implémente le transport stdio. La spécification MCP définit aussi un transport Streamable HTTP. Elle précise que les clients devraient prendre en charge stdio dès que possible, et qu’un serveur peut se limiter à stdio. Pour accéder aux mêmes outils par le réseau, utilise plutôt le transport REST ou gRPC — voir /transports/rest/ et /transports/grpc/.

Surface de l’API

Méthodes

Méthode	Comportement
`initialize`	Renvoie la version du protocole, les capacités et les informations sur le serveur
`notifications/initialized`	Une notification (sans `id`) ; acquittée sans réponse
`tools/list`	Liste les outils enregistrés ; filtre `params.category` facultatif
`tools/call`	Exécute l’outil désigné par `params.name` avec `params.arguments`

Toute autre méthode renvoie method-not-found (-32601). Un message qui n’est pas un JSON-RPC 2.0 valide renvoie invalid-request (-32600) ; une entrée non analysable renvoie parse-error (-32700). Un id de requête en double renvoie la réponse précédente mise en cache dans un tampon de 64 entrées, sans réexécution.

Réponse à initialize

Le résultat de initialize indique protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect, ainsi qu’un objet capabilities. Au-delà de la capacité standard tools, le serveur ajoute un bloc capabilities.nextpdf :

tiers — le nombre d’outils enregistrés par niveau au moment de l’exécution (core / pro / enterprise).
tool_count — le nombre total d’outils enregistrés, calculé à l’exécution.
risk_model_version — la version du modèle de risque appliquée par le serveur.
hitl_enabled — true ; le contrôle de confirmation est actif.

tool_count est le nombre qui fait foi pour ce déploiement. Il s’agit d’un décompte à l’exécution, pas d’une constante documentée ; voir /connect/tool-catalog/.

Exemple de code — Démarrage rapide

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

Exemple de code — Production

Une liste filtrée par catégorie limite le catalogue à un seul domaine :

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"category":"diagnostic"}}
EOF

Les valeurs possibles proviennent de la catégorie déclarée par chaque outil (par exemple document, diagnostic).

Cas limites et pièges

Pas de clé d’API. Le transport stdio n’a ni écouteur réseau ni jeton bearer. La confiance repose sur la frontière de processus du système d’exploitation, conformément au modèle stdio de MCP. Ne l’expose pas au réseau.
Les défis de confirmation sont transmis dans la bande. Un outil ApprovalRequired renvoie une réponse JSON-RPC réussie dont le contenu est le texte du défi et un jeton à usage unique, et non une erreur. Voir /connect/hitl-risk-tiers/.
Les notifications sont silencieuses. Un message sans id ne produit aucune réponse. La séquence de poignée de main est initialize (avec id), puis la notification initialized, puis les appels munis d’un id.

Performances

Le serveur MCP est un processus unique qui traite une requête à la fois via des tubes. Il n’y a pas d’aller-retour réseau ; la latence est dominée par le traitement du moteur sous-jacent.

Notes de sécurité

Le transport hérite de la confiance du client qui le lance. Garde le sous-processus en local. Les outils à haut risque restent protégés par une confirmation humaine, même sans clé d’API. Voir /connect/security-and-operations/.

Conformité

Le cadrage stdio et le comportement initialize/lifecycle sont conformes à la spécification officielle du Model Context Protocol, révision 2025-06-18 :

Transports : https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Cycle de vie : https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

La spécification MCP ne fait pas partie du corpus de normes sous licence, elle ne porte donc pas de reference_id ; les URL officielles ci-dessus font office de citation de référence.

Contexte commercial

tools/list ne renvoie les outils Pro et Enterprise que lorsque nextpdf/premium est installé avec le serveur. Le transport lui-même est identique quels que soient les niveaux installés.

Voir aussi

/connect/quickstart/ — exemple exécutable de poignée de main
/connect/tool-catalog/ — ce que renvoie tools/list et pourquoi le décompte varie
/connect/hitl-risk-tiers/ — le format du défi de confirmation
/transports/rest/ · /transports/grpc/ — alternatives en réseau
/connect/migrating-to-multi-transport/ — migrer une intégration uniquement MCP vers REST/gRPC