Von reinem MCP auf Multi-Transport migrieren

Auf einen Blick

Migrieren Sie eine Integration vom MCP-stdio-Transport auf den REST- oder gRPC-Transport. Das Verhalten der Engine bleibt unverändert. Katalog, Risikomodell und Bestätigungs-Gate bleiben identisch. Drei Dinge ändern sich: Wire-Protokoll, Authentifizierung und Nebenläufigkeitsmodell.

Installation

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

Konzeptioneller Überblick

Die frühe Dokumentation zu diesem Paket beschrieb einen einzigen Transport: MCP über stdio. Das Paket stellt jetzt dieselbe Tool-Registry über drei Transporte bereit. Die Migration umfasst zwei Schritte: Wählen Sie einen netzwerkfähigen Transport, und bilden Sie dann die MCP-Aufrufe darauf ab. Ihre Dokumentlogik wird dabei nicht neu geschrieben.

Wählen Sie den Transport, der zu Ihrem Deployment-Modell passt:

• Bleiben Sie bei MCP für einen einzelnen lokalen Agenten, die niedrigste Latenz (kein Netzwerk-Hop) oder einen MCP-nativen Client (zum Beispiel einen lokalen IDE-Assistenten).
• Wechseln Sie zu REST für Zugriff durch mehrere Clients mit API-Keys pro Client, Container- oder Kubernetes-Deployment, Rate Limiting pro Client, asynchrone Jobs oder Clients, die in einer beliebigen Sprache geschrieben sind.
• Wechseln Sie zu gRPC für typisierte Verträge, Server-Streaming großer PDFs und Service-zu-Service-Deployments mit mutual TLS.

API-Oberfläche

Was gleich bleibt

• Die Tool-Registry und der laufzeitabhängige Katalog (siehe /connect/tool-catalog/).
• Das vierstufige Risikomodell und das Bestätigungs-Gate (siehe /connect/hitl-risk-tiers/).
• Das Dokumentmodell und die Engine-Semantik.

Was sich ändert

Aspekt	MCP (stdio)	REST	gRPC
Wire-Format	JSON-RPC 2.0 über stdio	JSON über HTTP	Protobuf über gRPC
Authentifizierung	keine (lokaler Subprozess)	Authorization: Bearer API-Key	Bearer in den Call-Metadaten
Nebenläufigkeit	ein Prozess, ein Call	RoadRunner-Worker-Pool	RoadRunner-gRPC-Pool
Async	nicht anwendbar	Job-Endpunkte	Job-RPCs
Streaming	nicht anwendbar	synchroner Body	Server-Streaming-RPCs

Konzept-Zuordnung

Eine typische MCP-Sequenz ist create_pdf, dann Content-Tools, dann output_pdf. Bei REST wird daraus ein zustandsloses POST /api/v1/render mit einem geordneten operations-Array. Wenn Sie Zustand über einzelne Schritte hinweg benötigen, verwenden Sie stattdessen die optionalen Session-Endpunkte. Bei gRPC ist das Äquivalent der Render-RPC oder RenderStream für die Auslieferung in Chunks. Für zustandsbehaftete Builds verwenden Sie die RPCs CreateSession, SessionOperation und SessionRender.

MCP-Tool-Sequenz	REST	gRPC
create_pdf + Content-Tools + output_pdf	POST /api/v1/render	Render / RenderStream
Zustandsbehafteter Build über mehrere Calls hinweg	POST /api/v1/sessions (+ Session-Ops)	CreateSession (+ SessionOperation)
Langer Render-Vorgang	POST /api/v1/jobs, dann Ergebnis pollen	SubmitJob, dann GetJobResult
Stufengesteuerte Operation	POST /api/v1/<operation>	ExecuteCapability

Codebeispiel — Schnellstart

Der MCP-Call:

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

wird zum 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

Codebeispiel — Produktion

Betreiben Sie beide Transporte während einer schrittweisen Migration. Das kombinierte RoadRunner-Profil stellt REST und gRPC über einen einzigen Supervisor bereit. Die alte MCP-Integration läuft weiterhin lokal, wo dies weiterhin sinnvoll ist:

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

Es gibt keinen gemeinsamen Zustand, der migriert werden müsste. Die Transporte sind unabhängige Prozesse auf derselben Engine. Stellen Sie die Clients schrittweise um.

Sonderfälle und Stolperfallen

• Fügen Sie Authentifizierung hinzu. Der MCP-Transport hatte keine, weil er ein lokaler Subprozess ist. Die netzwerkfähigen Transporte verlangen bei jedem Request, der kein Health-Check ist, einen gültigen API-Key. Legen Sie die Keys vor der Umstellung an. Siehe /connect/security-and-operations/.

• Das Bestätigungs-Gate greift weiterhin. Ein approval_required-Tool fordert bei REST und gRPC genauso eine Bestätigung an wie zuvor bei MCP. Übernehmen Sie den Bestätigungs-Flow in die neue Integration. Gehen Sie nicht davon aus, dass das Gate nur für MCP gilt. Siehe /connect/hitl-risk-tiers/.

• Die Stufensteuerung bleibt unverändert. Eine Pro- oder Enterprise-Operation braucht ein installiertes nextpdf/premium und einen berechtigten Key auf dem neuen Transport, genauso, wie das entsprechende Tool das Paket bei MCP benötigte.

• Idempotenz ist neu und nützlich. REST fügt eine Idempotenz-Steuerung hinzu, die der stdio-Transport nie hatte. Nutzen Sie sie, um das Einreichen von Jobs gefahrlos wiederholbar zu machen. Siehe /connect/production-usage/.

Performance

MCP läuft in einem einzelnen Prozess und hat für einen einzelnen lokalen Agenten die niedrigste Latenz. Die netzwerkfähigen Transporte fügen einen Worker-Pool und einen Netzwerk-Hop hinzu. Im Gegenzug skalieren sie für viele gleichzeitige Clients. Verschieben Sie lange Render-Vorgänge auf dem neuen Transport in den asynchronen Job-Pfad, damit keine Worker blockiert bleiben.

Sicherheitshinweise

Die Migration weg von stdio bedeutet, dass Sie Netzwerkexposition einführen. Terminieren Sie TLS vor REST, nutzen Sie mutual TLS für gRPC in nicht vertrauenswürdigen Netzwerken, beschränken Sie Keys pro Client und halten Sie enabled_tools minimal. Das Modell des MCP-Transports ohne Credentials ist nur deshalb sicher, weil er ein lokaler Subprozess ist. Stellen Sie diese Exposition nicht über ein Netzwerk wieder her. Siehe /connect/security-and-operations/.

Konformität

Diese Seite ist eine Migrationsanleitung. Belege zu Protokoll und Authentifizierung sind in /transports/mcp/, /transports/rest/, /transports/grpc/ und /connect/security-and-operations/ fixiert.

Kommerzieller Kontext

Stufengesteuerte Operationen verlangen nextpdf/premium, unabhängig vom Transport. Die Migration ändert nicht, was zu Core und was zu Premium gehört. Sie ändert nur, wie auf den Katalog zugegriffen wird.

Siehe auch

• /transports/mcp/ — der Transport, von dem Sie migrieren
• /transports/rest/ · /transports/grpc/ — die Transporte, zu denen Sie migrieren
• /connect/tool-catalog/ — der Katalog, der über alle Transporte hinweg identisch ist
• /connect/hitl-risk-tiers/ — das Gate, das über alle Transporte hinweg identisch ist
• /connect/security-and-operations/ — die Authentifizierung, die Sie hinzufügen müssen