Migrar de MCP como único transporte a multitransporte

De un vistazo

Traslada una integración del transporte stdio de MCP al transporte REST o gRPC. El comportamiento del motor no cambia. El catálogo, el modelo de riesgo y la puerta de confirmación siguen siendo idénticos. Cambian tres aspectos: el protocolo de transmisión, la autenticación y el modelo de concurrencia.

Instalación

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

Panorama conceptual

La documentación inicial de este paquete describía un solo transporte: MCP sobre stdio. Ahora el paquete expone el mismo registro de herramientas mediante tres transportes. Migrar implica dos pasos: elegir un transporte de red y, después, hacer corresponder las llamadas de MCP con ese transporte. No requiere reescribir la lógica de los documentos.

Elegir el transporte que mejor se ajuste a la forma de despliegue:

Permanecer en MCP para un único agente local, la latencia más baja (sin salto de red) o un cliente MCP nativo (por ejemplo, un asistente de IDE local).
Pasar a REST para acceso de varios clientes con claves de API por cliente, despliegue en contenedores o Kubernetes, limitación de tasa por cliente, trabajos asíncronos o clientes escritos en cualquier lenguaje.
Pasar a gRPC para contratos tipados, transmisión desde el servidor de archivos PDF grandes y despliegues servicio a servicio con TLS mutuo.

Superficie de la API

Lo que se mantiene igual

El registro de herramientas y el catálogo dependiente del entorno de ejecución (véase /connect/tool-catalog/).
El modelo de riesgo de cuatro niveles y la puerta de confirmación (véase /connect/hitl-risk-tiers/).
El modelo de documento y la semántica del motor.

Lo que cambia

Aspecto	MCP (stdio)	REST	gRPC
Formato de transmisión	JSON-RPC 2.0 sobre stdio	JSON sobre HTTP	Protobuf sobre gRPC
Autenticación	ninguna (subproceso local)	`Authorization: Bearer` clave de API	bearer en los metadatos de la llamada
Concurrencia	un proceso, una llamada	grupo de workers de RoadRunner	grupo gRPC de RoadRunner
Asíncrono	no aplica	endpoints de trabajos	RPC de trabajos
Transmisión	no aplica	cuerpo síncrono	RPC con transmisión desde el servidor

Correspondencia de conceptos

Una secuencia típica en MCP es create_pdf, luego las herramientas de contenido y, después, output_pdf. En REST, esto se expresa como un único POST /api/v1/render sin estado con un arreglo operations ordenado. Cuando se necesite mantener estado paso a paso, usar en su lugar los endpoints de sesión opcionales. En gRPC, el equivalente es el RPC Render, o RenderStream para la entrega por fragmentos. Para construcciones con estado, usar los RPC CreateSession, SessionOperation y SessionRender.

Secuencia de herramientas de MCP	REST	gRPC
`create_pdf` + herramientas de contenido + `output_pdf`	`POST /api/v1/render`	`Render` / `RenderStream`
Construcción con estado entre llamadas	`POST /api/v1/sessions` (+ operaciones de sesión)	`CreateSession` (+ `SessionOperation`)
Renderizado largo	`POST /api/v1/jobs` y luego consultar el resultado	`SubmitJob` y luego `GetJobResult`
Operación controlada por nivel	`POST /api/v1/<operation>`	`ExecuteCapability`

Ejemplo de código — Inicio rápido

La llamada de MCP:

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

se convierte en esta solicitud 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

Ejemplo de código — Producción

Ejecutar ambos transportes durante una migración por fases. El perfil combinado de RoadRunner sirve REST y gRPC desde un solo supervisor. La integración antigua de MCP sigue funcionando localmente donde todavía resulte adecuada:

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

No hay estado compartido que migrar. Los transportes son procesos independientes sobre el mismo motor. Cambiar los clientes de forma incremental.

Casos límite y trampas

Agregar autenticación. El transporte de MCP no tenía ninguna porque es un subproceso local. Los transportes de red requieren una clave de API válida en cada solicitud que no sea de estado. Aprovisionar las claves antes del cambio. Véase /connect/security-and-operations/.
La puerta de confirmación se sigue activando. Una herramienta approval_required activa un desafío en REST y gRPC exactamente igual que en MCP. Trasladar el flujo de confirmación a la nueva integración. No asumir que la puerta es exclusiva de MCP. Véase /connect/hitl-risk-tiers/.
La restricción por nivel no cambia. Una operación Pro o Enterprise necesita nextpdf/premium instalado y una clave habilitada en el nuevo transporte, exactamente igual que la herramienta correspondiente necesitaba el paquete en MCP.
La idempotencia es nueva y útil. REST agrega un control de idempotencia que el transporte stdio nunca tuvo. Usarlo para que el envío de trabajos sea seguro de reintentar. Véase /connect/production-usage/.

Rendimiento

MCP se ejecuta en un solo proceso y ofrece la latencia más baja para un único agente local. Los transportes de red agregan un grupo de workers y un salto de red. A cambio, escalan para muchos clientes concurrentes. Trasladar los renderizados largos a la ruta de trabajos asíncronos en el nuevo transporte para que los workers no queden retenidos.

Notas de seguridad

Migrar fuera de stdio implica asumir exposición a la red. Terminar TLS delante de REST, usar TLS mutuo para gRPC en redes no confiables, limitar el alcance de las claves por cliente y mantener enabled_tools al mínimo. El modelo sin credenciales del transporte de MCP solo es seguro porque se ejecuta como subproceso local. No recrear esa exposición a través de una red. Véase /connect/security-and-operations/.

Conformidad

Esta página es una guía de migración. Las citas de protocolo y autenticación quedan fijadas en /transports/mcp/, /transports/rest/, /transports/grpc/ y /connect/security-and-operations/.

Contexto comercial

Las operaciones controladas por nivel requieren nextpdf/premium sin importar el transporte. Migrar no cambia qué pertenece a core frente a Premium. Solo cambia la forma de acceder al catálogo.

Véase también

/transports/mcp/ — el transporte desde el que se migra
/transports/rest/ · /transports/grpc/ — los transportes a los que se migra
/connect/tool-catalog/ — el catálogo, que es idéntico en todos los transportes
/connect/hitl-risk-tiers/ — la puerta, que es idéntica en todos los transportes
/connect/security-and-operations/ — la autenticación que debe agregarse