Migrazione da MCP come unico trasporto al multi-trasporto

In breve

Spostare un’integrazione dal trasporto MCP stdio al trasporto REST o gRPC. Il comportamento del motore non cambia. Il catalogo, il modello di rischio e il gate di conferma rimangono identici. Tre elementi cambiano: protocollo di trasmissione, autenticazione e modello di concorrenza.

Installazione

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

Panoramica concettuale

La documentazione iniziale di questo pacchetto descriveva un solo trasporto: MCP su stdio. Ora il pacchetto fornisce lo stesso registro di strumenti su tre trasporti. La migrazione richiede due passaggi: scegliere un trasporto di rete e quindi mappare su di esso le chiamate MCP. Non richiede di riscrivere la logica dei documenti.

Scegliere il trasporto più adatto alla propria configurazione di distribuzione:

Rimanere su MCP quando serve un singolo agente locale, la latenza più bassa (nessun salto di rete) o un client MCP nativo (ad esempio un assistente IDE locale).
Passare a REST quando servono accesso multi-client con chiavi API per singolo client, distribuzione su container o Kubernetes, limitazione della frequenza per singolo client, processi asincroni o client scritti in qualsiasi linguaggio.
Passare a gRPC quando servono contratti tipizzati, streaming lato server di PDF di grandi dimensioni e distribuzioni service-to-service con TLS reciproco.

Superficie dell’API

Cosa rimane invariato

Il registro degli strumenti e il catalogo dipendente dal runtime (vedere /connect/tool-catalog/).
Il modello di rischio a quattro livelli e il gate di conferma (vedere /connect/hitl-risk-tiers/).
Il modello dei documenti e la semantica del motore.

Cosa cambia

Aspetto	MCP (stdio)	REST	gRPC
Formato di trasmissione	JSON-RPC 2.0 su stdio	JSON su HTTP	Protobuf su gRPC
Autenticazione	nessuna (sottoprocesso locale)	`Authorization: Bearer` chiave API	bearer nei metadati della chiamata
Concorrenza	un processo, una chiamata	pool di worker RoadRunner	pool gRPC RoadRunner
Asincrono	non applicabile	endpoint dei processi	RPC dei processi
Streaming	non applicabile	corpo sincrono	RPC con streaming dal server

Mappatura dei concetti

Una sequenza MCP tipica è create_pdf, seguita dagli strumenti per il contenuto e infine da output_pdf. Su REST tutto questo corrisponde a un’unica POST /api/v1/render stateless con un array operations ordinato. Quando serve uno stato passo passo, utilizzare invece gli endpoint di sessione opzionali. Su gRPC l’equivalente è l’RPC Render oppure RenderStream per la consegna a blocchi. Per le build stateful, utilizzare gli RPC CreateSession, SessionOperation e SessionRender.

Sequenza di strumenti MCP	REST	gRPC
`create_pdf` + strumenti per il contenuto + `output_pdf`	`POST /api/v1/render`	`Render` / `RenderStream`
Build stateful su più chiamate	`POST /api/v1/sessions` (+ operazioni di sessione)	`CreateSession` (+ `SessionOperation`)
Rendering lungo	`POST /api/v1/jobs` quindi recuperare il risultato tramite polling	`SubmitJob` quindi `GetJobResult`
Operazione vincolata al livello	`POST /api/v1/<operation>`	`ExecuteCapability`

Esempio di codice — Avvio rapido

La chiamata MCP:

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

diventa la richiesta 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

Esempio di codice — Produzione

Eseguire entrambi i trasporti durante una migrazione graduale. Il profilo RoadRunner combinato espone REST e gRPC da un unico supervisore. La vecchia integrazione MCP continua a funzionare localmente dove rimane adatta:

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

Non c’è alcuno stato condiviso da migrare. I trasporti sono processi indipendenti sullo stesso motore. Migrare i client in modo incrementale.

Casi limite e insidie

Aggiungere l’autenticazione. Il trasporto MCP non ne prevedeva alcuna perché è un sottoprocesso locale. I trasporti di rete richiedono una chiave API valida per ogni richiesta, a eccezione di quelle di health. Predisporre le chiavi prima del passaggio. Vedere /connect/security-and-operations/.
Il gate di conferma si attiva comunque. Uno strumento approval_required richiede la conferma su REST e gRPC esattamente come su MCP. Trasferire il flusso di conferma nella nuova integrazione. Non dare per scontato che il gate sia esclusivo di MCP. Vedere /connect/hitl-risk-tiers/.
Il vincolo di livello rimane invariato. Un’operazione Pro o Enterprise richiede nextpdf/premium installato e una chiave abilitata sul nuovo trasporto, esattamente come lo strumento corrispondente richiedeva il pacchetto su MCP.
L’idempotenza è una novità utile. REST aggiunge un controllo di idempotenza che il trasporto stdio non ha mai avuto. Utilizzarlo per ritentare in sicurezza l’invio dei processi. Vedere /connect/production-usage/.

Prestazioni

MCP è a processo singolo e offre la latenza più bassa per un singolo agente locale. I trasporti di rete aggiungono un pool di worker e un salto di rete. In compenso, scalano su molti client simultanei. Spostare i rendering lunghi sul percorso dei processi asincroni del nuovo trasporto, così da non occupare i worker.

Note sulla sicurezza

Abbandonare stdio significa accettare un’esposizione di rete. Terminare il TLS davanti a REST, utilizzare il TLS reciproco per gRPC su reti non attendibili, limitare le chiavi al singolo client e mantenere enabled_tools al minimo. Il modello senza credenziali del trasporto MCP è sicuro solo perché opera come sottoprocesso locale. Non ricreare tale esposizione su una rete. Vedere /connect/security-and-operations/.

Conformità

Questa pagina fornisce indicazioni per la migrazione. Le citazioni relative al protocollo e all’autenticazione sono ancorate in /transports/mcp/, /transports/rest/, /transports/grpc/ e /connect/security-and-operations/.

Contesto commerciale

Le operazioni vincolate al livello richiedono nextpdf/premium indipendentemente dal trasporto. La migrazione non cambia ciò che rientra nel core rispetto a Premium. Cambia solo il modo in cui si accede al catalogo.

Vedere anche

/transports/mcp/ — il trasporto da cui si migra
/transports/rest/ · /transports/grpc/ — i trasporti verso cui si migra
/connect/tool-catalog/ — il catalogo, identico su tutti i trasporti
/connect/hitl-risk-tiers/ — il gate, identico su tutti i trasporti
/connect/security-and-operations/ — l’autenticazione da aggiungere