Resolución de problemas en NextPDF Connect

De un vistazo

La mayoría de los fallos pertenecen a uno de cinco grupos: un handshake de JSON-RPC mal formado, una clave de API ausente, una herramienta que no está instalada en este nivel, un desafío de confirmación sin respuesta o un store que no se comparte entre los workers. Cada grupo tiene una firma distintiva.

Instalación

composer require nextpdf/server

Visión conceptual

El transporte MCP devuelve objetos de error de JSON-RPC 2.0 con códigos estándar. El transporte REST devuelve documentos de detalles de problema de RFC 7807. Cada uno incluye una URL type que identifica la condición. Para problemas de entorno, empieza por las herramientas de diagnóstico (diagnostic.doctor, diagnostic.capabilities). Estas herramientas siempre están en el catálogo principal.

Superficie de la API

Códigos de error de JSON-RPC de MCP

Código	Nombre	Causa
`-32700`	Error de análisis	La línea no contenía JSON válido
`-32600`	Solicitud no válida	No es un mensaje JSON-RPC 2.0 (falta `jsonrpc`/`method`)
`-32601`	Método no encontrado	Se usó un método distinto de `initialize`, `tools/list`, `tools/call`
`-32602`	Parámetros no válidos	Falta `params.name` en `tools/call`
`-32603`	Error interno	La herramienta generó una excepción durante la ejecución

Una herramienta que falla de forma controlada no usa estos códigos. En su lugar, devuelve una respuesta JSON-RPC correcta cuyo resultado contiene isError: true y una explicación en texto, como herramienta desconocida, deshabilitada por política o argumentos no válidos.

Tipos de detalles de problema de REST

HTTP	`type` (slug)	Causa
`401`	`unauthorized`	Clave de API ausente, no válida, deshabilitada o vencida
`403`	`capability-denied`	El nivel de la clave no tiene derecho a la operación
`413`	`payload-too-large` / `tier-payload-exceeded`	El cuerpo supera el límite global o el del nivel
`422`	`validation-failed`	El cuerpo de la solicitud no superó la validación de esquema
`429`	`ip-rate-exceeded` / `client-rate-exceeded`	Se alcanzó un límite de tasa
`404`	`not-found`	Ruta desconocida o id de job/session
`504`	(tiempo de espera de la solicitud agotado)	La operación excedió el tiempo de espera del nivel

Ejemplo de código: inicio rápido

Ejecuta la comprobación de estado del entorno. No requiere ningún documento ni confirmación:

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

Ejemplo de código: producción

Confirma qué herramientas expone este despliegue antes de depurar una «herramienta ausente»:

./vendor/bin/generate-skills --dry-run --list-tools

o, contra un servidor REST en ejecución:

curl -sS http://localhost:8080/api/v1/capabilities \
  -H "Authorization: Bearer $NEXTPDF_KEY"

Casos límite y trampas

«Herramienta desconocida» para una herramienta Pro/Enterprise. El paquete de la herramienta no está instalado. El registro inspecciona las clases de proveedor y omite sin avisar los niveles ausentes. Es el comportamiento esperado, no un error. Instala nextpdf/premium junto al servidor, o usa una herramienta principal. El mensaje de error incluye la ruta de instalación.
Una herramienta que configuré en enabled_tools no aparece. La lista de permitidos se cruza con las herramientas descubiertas. No se puede añadir una herramienta que el registro no encontró. Revisa la instalación del nivel y cualquier control de entorno. Por ejemplo, parse_pdf es opcional mediante NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED.
tools/call devolvió texto que pide un token. Ese es el desafío de confirmación, no un error. Vuelve a llamar a la herramienta con _confirmation_token y el valor del token emitido dentro de un plazo de 300 segundos. Consulta /connect/hitl-risk-tiers/.
La línea de notificación no produjo salida. Eso es correcto. Un mensaje JSON-RPC sin id es una notificación, y el handler no devuelve nada. Envía solicitudes con un id para obtener respuestas.
Un id de solicitud repetido devolvió una respuesta obsoleta. El handler elimina duplicados por id de solicitud en un buffer de 64 entradas. Usa un id nuevo para cada solicitud lógica.
Los límites de tasa se comportan de forma extraña entre los workers. El store en memoria es por worker. Para compartir el conteo, define NEXTPDF_REDIS_HOST e instala ext-redis. Consulta /connect/deployment/.
Los documentos desaparecen entre solicitudes. El store de documentos en memoria es por worker y está limitado por un tiempo de vida (document_ttl, 1800 s de forma predeterminada). Para mantener la continuidad de documentos entre workers, usa el store respaldado por Redis, los endpoints de sesión o mantén todo el conjunto de operaciones en un único render síncrono.
El servidor recurrió a memoria a pesar de la configuración de Redis. El servidor REST usa automáticamente la alternativa si la conexión con Redis falla en el arranque. Comprueba que Redis sea accesible y confirma que ext-redis esté presente en la imagen en ejecución. No des por hecho que Redis está en uso sin verificarlo.
El servidor se niega a arrancar con un error de configuración. Una entrada de risk_level_overrides intentó rebajar una herramienta ApprovalRequired. El cargador rechaza esto por diseño. Elimina la rebaja; las anulaciones solo pueden aumentar el riesgo.

Rendimiento

Si los renders son lentos bajo carga, confirma que el pool de workers no esté saturado. Revisa el endpoint de métricas de RoadRunner. Luego mueve los renders largos a la ruta de jobs asíncronos para que los workers no queden bloqueados. Consulta /connect/production-usage/.

Notas de seguridad

No sortees un 401 exponiendo el transporte MCP sin autenticarlo a través de una red: eso elimina la autenticación por completo. En su lugar, corrige la clave de API. No aumentes el nivel de detalle del registro para inspeccionar los argumentos de las herramientas en un entorno compartido; las cargas de argumentos pueden ser sensibles. Consulta /connect/security-and-operations/.

Conformidad

Esta página es una guía operativa. Las citas de protocolo y seguridad están fijadas en /transports/mcp/, /transports/rest/ y /connect/security-and-operations/.

Consulta también

/connect/tool-catalog/ — qué incluye el catálogo principal y por qué varía el recuento
/connect/hitl-risk-tiers/ — los desafíos de confirmación en detalle
/connect/deployment/ — Redis, pools de workers y store compartido
/connect/security-and-operations/ — fallos de autenticación y postura