NextPDF Connect — transporte MCP

De un vistazo

El transporte MCP ejecuta bin/nextpdf-mcp como un subproceso local. Se comunica mediante JSON-RPC 2.0 a través de la entrada y la salida estándar. El servidor implementa la revisión de MCP fechada 2025-06-18.

Instalación

composer require nextpdf/server

Visión general conceptual

En el modelo stdio de MCP, el cliente inicia el servidor como un subproceso. El cliente intercambia mensajes JSON-RPC delimitados por saltos de línea: un mensaje por línea, sin saltos de línea incrustados, en UTF-8. El servidor escribe solo mensajes MCP válidos en la salida estándar y usa la salida de error estándar para el registro. La implementación dirige su registrador de auditoría a la salida de error estándar precisamente para que las líneas de registro nunca corrompan el flujo del protocolo. Esta delimitación la define la especificación oficial de MCP, revisión 2025-06-18. Esa especificación no forma parte del corpus de estándares controlado, por lo que se cita mediante URL: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect implementa el transporte stdio. La especificación de MCP también define un transporte Streamable HTTP. La especificación indica que los clientes deberían admitir stdio siempre que sea posible, y que un servidor puede implementar solo stdio. Para acceder por red a las mismas herramientas, debe usarse en su lugar el transporte REST o gRPC; véase /transports/rest/ y /transports/grpc/.

Superficie de la API

Métodos

Método	Comportamiento
`initialize`	Devuelve la versión del protocolo, las capacidades y la información del servidor
`notifications/initialized`	Notificación (sin `id`) que se confirma sin respuesta
`tools/list`	Devuelve la lista de herramientas registradas; filtro `params.category` opcional
`tools/call`	Ejecuta una herramienta por `params.name` con `params.arguments`

Cualquier otro método devuelve método-no-encontrado (-32601). Un mensaje que no sea JSON-RPC 2.0 válido devuelve solicitud-no-válida (-32600); una entrada que no pueda analizarse devuelve error-de-análisis (-32700). Una solicitud con un id duplicado devuelve la respuesta previa almacenada en caché en un búfer de 64 entradas, sin volver a ejecutarla.

La respuesta de initialize

El resultado de initialize informa de protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect y un objeto capabilities. Además de la capacidad tools estándar, el servidor añade un bloque capabilities.nextpdf:

tiers: los recuentos de herramientas registradas por nivel activo (core / pro / enterprise).
tool_count: el número total de herramientas registradas, calculado en tiempo de ejecución.
risk_model_version: la versión del modelo de riesgo que aplica el servidor.
hitl_enabled: true; la compuerta de confirmación está activa.

tool_count es el número de referencia para este despliegue. Es un recuento en tiempo de ejecución, no una constante documentada; véase /connect/tool-catalog/.

Ejemplo de código — Inicio rápido

./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

Ejemplo de código — Producción

Un listado filtrado por categoría limita el catálogo a un solo dominio:

./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

Los valores de categoría proceden de la categoría declarada de cada herramienta (por ejemplo document, diagnostic).

Casos límite y advertencias

Sin clave de API. El transporte stdio no escucha en red ni usa token de portador. El límite de confianza es el proceso del sistema operativo, según el modelo stdio de MCP. No debe conectarse a una red.
Los desafíos de confirmación viajan en banda. Una herramienta ApprovalRequired devuelve una respuesta JSON-RPC correcta cuyo contenido es el texto del desafío y un token de un solo uso, no un error. Véase /connect/hitl-risk-tiers/.
Las notificaciones son silenciosas. Un mensaje sin id no produce respuesta. El protocolo de enlace sigue este orden: initialize (con id), luego la notificación initialized y luego las llamadas con id.

Rendimiento

El servidor MCP es un único proceso que atiende una solicitud a la vez a través de tuberías. No hay ida y vuelta por la red; la latencia está dominada por la operación del motor subyacente.

Notas de seguridad

El transporte hereda la confianza del cliente que lo lanza. Debe mantenerse el subproceso en local. Las herramientas de alto riesgo siguen estando controladas por confirmación humana, aunque no haya clave de API. Véase /connect/security-and-operations/.

Conformidad

La delimitación stdio y el comportamiento de initialize/lifecycle son conformes a la especificación oficial del Model Context Protocol, revisión 2025-06-18:

Transportes: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Ciclo de vida: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

La especificación de MCP no está en el corpus de estándares controlado, por lo que no tiene ningún reference_id; las URL oficiales anteriores son la cita de referencia.

Contexto comercial

tools/list devuelve las herramientas Pro y Enterprise solo cuando nextpdf/premium está instalado junto al servidor. El transporte en sí es idéntico con independencia de los niveles instalados.

Véase también

/connect/quickstart/ — el protocolo de enlace ejecutable
/connect/tool-catalog/ — qué devuelve tools/list y por qué varía el recuento
/connect/hitl-risk-tiers/ — el formato del desafío de confirmación
/transports/rest/ · /transports/grpc/ — alternativas de red
/connect/migrating-to-multi-transport/ — migrar una integración basada solo en MCP a REST/gRPC