Referencia de la API de NextPDF Connect

De un vistazo

Esta página es la referencia por símbolo del servidor NextPDF Connect (nextpdf/server). Enumera cada herramienta por su nombre registrado y su clase de implementación, y documenta el servicio gRPC NextPDFConnect, incluidos sus métodos de llamada a procedimiento remoto (RPC) y sus mensajes de solicitud y respuesta. También fija el contrato de autenticación, errores y límites de tasa que comparten todos los transportes.

El servidor expone un único registro de herramientas mediante tres transportes: Model Context Protocol (MCP) sobre entrada y salida estándar, una interfaz de programación de aplicaciones (API) REST y gRPC. Los detalles de comunicación de cada transporte están en su propia página: consulta Transporte MCP, Transporte REST y Transporte gRPC. Esta página es el catálogo de símbolos que esos transportes exponen.

Los nombres de herramienta, las clases y los niveles de riesgo siguientes se leen desde las implementaciones de las herramientas en src/Tools/. El número de herramientas que un despliegue expone realmente se determina en tiempo de ejecución; consulta Catálogo de herramientas. La resolución de niveles se explica en Arranque y descubrimiento.

Disponibilidad de transportes

Una herramienta es accesible a través de cualquier transporte que un despliegue tenga en ejecución. Los transportes son procesos independientes; ejecutar uno no inicia los demás.

Transporte	Punto de entrada	Formato de comunicación	Autenticación
MCP	bin/nextpdf-mcp	Llamada a procedimiento remoto con notación de objetos de JavaScript (JSON-RPC) 2.0 sobre stdio	Límite de proceso del sistema operativo (sin clave de API)
REST	bin/nextpdf-server	HTTP, OpenAPI 3.1	Clave de API de tipo bearer en el encabezado Authorization de la solicitud
gRPC	bin/nextpdf-grpc	Protocol Buffers, paquete nextpdf.connect.v1	Token de tipo bearer en el campo authorization de los metadatos de llamada

En MCP, una herramienta se llama mediante tools/call con el nombre de herramienta registrado. En REST y gRPC, se accede a las mismas capacidades del motor a través de las interfaces de renderizado, operación y capacidad; consulta la tabla de rutas de Transporte REST y la tabla de RPC de Transporte gRPC.

Autenticación y nivel de riesgo

Autenticación con clave de API

Los transportes REST y gRPC requieren una clave de API de tipo bearer en cada solicitud, excepto en las sondas de salud no autenticadas. Una clave tiene la forma npk_live_{kid}_{secret}: el kid es un identificador de ocho caracteres para buscar registros, y el secreto contiene la entropía. El servidor almacena únicamente un resumen SHA-256 de la clave y compara el token presentado con una comparación en tiempo constante, de modo que una clave incorrecta no filtra información por temporización. REST lee el token desde la cabecera Authorization: Bearer …; gRPC lee el mismo token desde los metadatos de llamada authorization. El transporte stdio de MCP no usa clave de API porque es un subproceso local de confianza para el cliente que lo lanza. El modelo de autenticación está documentado en su totalidad en Seguridad y operaciones.

Los cuatro niveles de riesgo

Cada herramienta declara uno de cuatro niveles de riesgo ordenados, definidos por el enum RiskLevel en src/Config/RiskLevel.php.

Nivel	Caso del enum	Valor	Efecto
Safe	RiskLevel::Safe	0	Solo lectura, sin efectos secundarios. Se ejecuta automáticamente.
Caution	RiskLevel::Caution	1	Crea o modifica estado en memoria. Se ejecuta automáticamente, con registro de auditoría.
Review	RiskLevel::Review	2	Produce una salida que podría usarse de forma indebida. Se ejecuta automáticamente, con registro de auditoría.
ApprovalRequired	RiskLevel::ApprovalRequired	3	Destructiva, legal o crítica para la privacidad. Requiere confirmación humana.

El riesgo efectivo de una herramienta se determina exclusivamente a partir de dos fuentes: la propia declaración riskLevel() de la herramienta y una anulación de configuración opcional del operador que solo puede elevar el riesgo, nunca reducir una herramienta ApprovalRequired. Consulta Niveles de riesgo HITL y Configuración.

Cómo fluyen los tokens de aprobación

Cuando se invoca una herramienta ApprovalRequired sin un token válido, el ConfirmationGate (src/Mcp/ConfirmationGate.php) devuelve un token de desafío de un solo uso en lugar de ejecutar la herramienta. El agente transmite el desafío a una persona y, a continuación, vuelve a invocar la misma herramienta con el token emitido en el argumento _confirmation_token. El token queda vinculado al nombre de la herramienta, a un nonce aleatorio y a un tiempo de vida (TTL) de 300 segundos. No queda vinculado a los argumentos y no es una credencial de autenticación. En REST, la clave de API de tipo bearer sigue autenticando la solicitud, y la misma compuerta se ejecuta en el ejecutor de herramientas compartido antes de la operación controlada. En gRPC, la misma compuerta se ejecuta antes de la operación despachada. El mecanismo de desafío y token es idéntico en todos los transportes.

Herramientas y endpoints

La tabla documenta cada herramienta por su nombre registrado (columna Símbolo) e indica su clase de implementación. Las herramientas se agrupan por nivel y categoría. Todas las clases de AST y de mutación residen bajo src/Tools/Ast y src/Tools/Ast/Mutation; la clase de extracción reside bajo src/Tools/Extraction; las clases restantes residen bajo src/Tools/Core.

Herramientas de documentos del nivel Core

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
create_pdf	page_size (predeterminado A4), orientation (portrait/landscape), title, author; ninguno obligatorio.	Crea un documento en memoria y una página; establece los metadatos cuando se proporcionan.	JSON con document_id, page_count, page_size, orientation.	Devuelve un resultado de error con el mensaje del motor en caso de fallo.	Clase CreatePdfTool. Riesgo RiskLevel::Caution. Nivel core. El document_id devuelto alimenta cada operación posterior.
add_page	document_id (obligatorio), tamaño de página y orientación opcionales.	Añade una página al documento.	JSON con el nuevo número de páginas.	Resultado de error cuando el document_id es desconocido.	Clase AddPageTool. Riesgo RiskLevel::Caution. Nivel core.
add_text	document_id (obligatorio), text (obligatorio), posición y estilo opcionales.	Añade texto al documento.	Resumen JSON del estado del documento.	Resultado de error cuando el document_id es desconocido.	Clase AddTextTool. Riesgo RiskLevel::Caution. Nivel core.
add_image	document_id (obligatorio), source (obligatorio: ruta de archivo o base64), ubicación opcional.	Añade una imagen desde una ruta o datos base64.	Resumen JSON del estado del documento.	Resultado de error en caso de fuente ilegible o document_id desconocido.	Clase AddImageTool. Riesgo RiskLevel::Caution. Nivel core.
add_table	document_id (obligatorio), html (obligatorio).	Renderiza una tabla en lenguaje de marcado de hipertexto (HTML) en el documento.	Resumen JSON del estado del documento.	Resultado de error en caso de marcado no válido o document_id desconocido.	Clase AddTableTool. Riesgo RiskLevel::Caution. Nivel core.
set_font	document_id (obligatorio), family (obligatorio), tamaño y estilo opcionales.	Establece la fuente para las operaciones de texto posteriores.	Confirmación JSON de la fuente activa.	Resultado de error en caso de fuente desconocida o document_id desconocido.	Clase SetFontTool. Riesgo RiskLevel::Caution. Nivel core.
output_pdf	document_id (obligatorio), file_path (opcional), destroy (predeterminado true).	Finaliza el documento; escribe en file_path, o devuelve base64 cuando se omite; destruye el documento de forma predeterminada.	JSON con file_path y file_size, o base64 y file_size.	Resultado de error cuando el document_id es desconocido; fallo de contención de ruta al escribir fuera del directorio base.	Clase OutputPdfTool. Riesgo RiskLevel::ApprovalRequired. Nivel core. La escritura de un archivo pasa por la compuerta de confirmación; el modo base64 no.
preview_layout	document_id (obligatorio).	Devuelve un resumen de la maquetación sin renderizar el PDF final.	Resumen JSON de la maquetación.	Resultado de error cuando el document_id es desconocido.	Clase PreviewLayoutTool. Riesgo RiskLevel::Safe. Nivel core.
parse_pdf	document_id (obligatorio).	Inspecciona los metadatos estructurales: número de páginas, fuentes, imágenes, cifrado y diccionario de información (Info Dictionary).	Metadatos estructurales en JSON.	Resultado de error en caso de documento mal formado.	Clase ParsePdfTool. Riesgo RiskLevel::Safe. Nivel core. Se registra únicamente cuando NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED es true o 1.

Herramientas de diagnóstico del nivel Core

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
diagnostic.doctor	ninguno.	Ejecuta una comprobación de salud y devuelve diagnósticos estructurados del entorno.	Informe JSON del entorno.	Resultado de error en caso de fallo de una comprobación interna.	Clase DiagnosticDoctorTool. Riesgo RiskLevel::Safe. Nivel core. No necesita documento ni confirmación.
diagnostic.capabilities	ninguno.	Enumera las capacidades con información de nivel y estado.	Lista JSON de capacidades.	Resultado de error en caso de fallo interno.	Clase DiagnosticCapabilitiesTool. Riesgo RiskLevel::Safe. Nivel core.
diagnostic.inspect	document_id (obligatorio).	Inspecciona un PDF y devuelve metadatos estructurales.	Metadatos estructurales en JSON.	Resultado de error cuando el document_id es desconocido.	Clase DiagnosticInspectTool. Riesgo RiskLevel::Safe. Nivel core.
diagnostic.verify	document_id (obligatorio), perfil PDF/A o PDF/UA opcional.	Verifica la integridad estructural; opcionalmente valida PDF/A o PDF/UA mediante un subproceso de VeraPDF.	Informe JSON de verificación.	Resultado de error en caso de fallo del subproceso, tiempo de espera agotado o entrada de tamaño excesivo.	Clase DiagnosticVerifyTool. Riesgo RiskLevel::Caution. Nivel core. La entrada está limitada a 50 mebibytes (MiB).

Herramienta de códigos de barras del nivel Core

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
generate_barcode	payload (obligatorio), format (por ejemplo, QR Code, DataMatrix).	Genera una matriz de módulos de código de barras bidimensional para el payload.	Matriz de módulos en JSON.	Resultado de error en caso de format no admitido o payload no válido.	Clase BarcodeTool. Riesgo RiskLevel::Caution. Nivel core. La BarcodeTool se registra únicamente cuando el registro de codificadores de barcode del núcleo está presente en el nextpdf/core instalado; el nombre registrado de la herramienta es generate_barcode.

Herramientas de privacidad del nivel Enterprise

Estas herramientas envuelven clases de privacidad de Enterprise y se registran en el nivel Enterprise únicamente cuando esas clases se pueden cargar automáticamente. Operan sobre contenido de texto plano.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
redact_pdf	content (obligatorio), opciones de detección opcionales.	Redacta de forma destructiva la información de identificación personal (PII) en contenido de texto plano usando el motor de redacción de Enterprise.	JSON con el contenido redactado y un hash SHA-256.	Resultado de error cuando las clases de Enterprise están ausentes o la detección falla.	Clase RedactPdfTool. Riesgo RiskLevel::Review. Nivel enterprise.
deidentify_pdf	content (obligatorio), strategy (redactar o suprimir).	Aplica una estrategia sistemática de desidentificación a contenido de texto plano usando el desidentificador de Enterprise.	JSON con el contenido desidentificado.	Resultado de error cuando las clases de Enterprise están ausentes.	Clase DeIdentifyPdfTool. Riesgo RiskLevel::Review. Nivel enterprise.
zone_redact_pdf	content (obligatorio), zones (página más lista de rectángulos normalizados).	Aplica redacciones de zona basadas en coordenadas usando el motor de redacción de Enterprise.	JSON con el contenido redactado.	Resultado de error en caso de zona no válida o ausencia de las clases de Enterprise.	Clase ZoneRedactionTool. Riesgo RiskLevel::Review. Nivel enterprise.

Herramientas de lectura del árbol de sintaxis abstracta (AST)

Estas herramientas se incluyen con el servidor, se registran en el nivel Pro y están controladas por NEXTPDF_AST_TOOLS_ENABLED (habilitado de forma predeterminada). Son de solo lectura.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
get_document_ast	pdf_data (obligatorio).	Construye un AST semántico: un árbol de nodos completo con anclas de citación para cada elemento estructural.	Árbol de nodos en JSON más un ETag para el control de concurrencia.	Resultado de error en caso de documento mal formado.	Clase GetDocumentAstTool. Riesgo RiskLevel::Safe. Nivel pro.
get_ast_node	pdf_data (obligatorio), node_id (obligatorio).	Recupera un único nodo del AST y todos sus hijos.	Nodo JSON con sus hijos.	Resultado de error en caso de node_id desconocido.	Clase GetAstNodeTool. Riesgo RiskLevel::Safe. Nivel pro.
get_ast_diff	original_pdf_data (obligatorio), modified_pdf_data (obligatorio).	Calcula la diferencia estructural entre dos documentos comparando sus AST semánticos.	JSON con los nodos añadidos, eliminados y modificados.	Resultado de error en caso de documento de entrada mal formado.	Clase GetAstDiffTool. Riesgo RiskLevel::Safe. Nivel pro.
search_ast_nodes	pdf_data (obligatorio), tipo, índice de página y filtros de texto opcionales.	Busca nodos del AST por tipo, índice de página o contenido de texto.	Lista plana en JSON de los nodos coincidentes con sus hijos superficiales.	Resultado de error en caso de documento mal formado.	Clase SearchAstNodesTool. Riesgo RiskLevel::Safe. Nivel pro.
extract_cited_text	pdf_data (obligatorio), headings_only opcional.	Extrae bloques de texto con anclas de citación (página, recuadro delimitador, confianza).	Bloques de texto citados en JSON.	Resultado de error en caso de documento mal formado.	Clase ExtractCitedTextTool. Riesgo RiskLevel::Safe. Nivel pro. Categoría ast.
extract_cited_tables	pdf_data (obligatorio).	Extrae bloques de tabla con anclas de citación; devuelve una matriz de celdas en orden de filas para cada nodo Table.	Matrices de tabla en JSON con anclas.	Resultado de error en caso de documento mal formado.	Clase ExtractCitedTablesTool. Riesgo RiskLevel::Safe. Nivel pro. Categoría extraction.

Herramientas de mutación del AST

Estas herramientas se incluyen con el servidor, se registran en el nivel Pro y están controladas por NEXTPDF_MUTATION_TOOLS_ENABLED (habilitado de forma predeterminada). Las cuatro son ApprovalRequired y usan control de concurrencia optimista (OCC) mediante un ETag.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
apply_ast_mutations	pdf_data, etag, idempotency_key, mutations (todos obligatorios).	Aplica un lote de mutaciones de forma atómica; devuelve el resultado almacenado en caché para un idempotency_key repetido.	JSON con el PDF mutado y un nuevo ETag.	Conflicto de OCC cuando el ETag está obsoleto; error de validación en caso de mutación mal formada.	Clase ApplyAstMutationsTool. Riesgo RiskLevel::ApprovalRequired. Nivel pro.
delete_ast_node	pdf_data, node_id, etag (todos obligatorios).	Elimina un nodo en modo superposición (el contenido original se cubre, no se elimina físicamente).	JSON con el PDF modificado y un nuevo ETag.	Conflicto de OCC cuando el ETag está obsoleto; error en caso de node_id desconocido.	Clase DeleteAstNodeTool. Riesgo RiskLevel::ApprovalRequired. Nivel pro.
insert_ast_node	pdf_data, parent_node_id, position, etag, node (todos obligatorios).	Inserta un nuevo nodo como hijo del padre en la posición indicada.	JSON con el PDF modificado y un nuevo ETag.	Conflicto de OCC cuando el ETag está obsoleto; error de validación en caso de nodo mal formado.	Clase InsertAstNodeTool. Riesgo RiskLevel::ApprovalRequired. Nivel pro.
update_ast_node	pdf_data, node_id, etag, updates (todos obligatorios).	Actualiza el contenido de texto de un nodo.	JSON con el PDF modificado y un nuevo ETag.	Conflicto de OCC cuando el ETag está obsoleto; error en caso de node_id desconocido.	Clase UpdateAstNodeTool. Riesgo RiskLevel::ApprovalRequired. Nivel pro.

Esquema de solicitud y respuesta

El transporte gRPC define el esquema tipado del servidor en el paquete de Protocol Buffers nextpdf.connect.v1, en proto/nextpdf/connect/v1/*.proto. El servicio y sus mensajes son los símbolos canónicos del esquema.

Servicio NextPDFConnect

El servicio NextPDFConnect expone RPC unarios y de streaming desde el servidor. Los símbolos del esquema son los nombres de los métodos RPC y los mensajes de solicitud y respuesta que transportan.

RPC	Mensaje de solicitud	Mensaje de respuesta	Forma
Render	RenderRequest	RenderResponse	Unario. Renderizado sin estado y síncrono.
RenderStream	RenderRequest	RenderChunk (stream)	Streaming desde el servidor. Renderizado entregado como fragmentos ordenados.
SubmitJob	SubmitJobRequest	JobResponse	Unario. Envía un trabajo de renderizado asíncrono.
GetJobStatus	GetJobStatusRequest	JobResponse	Unario. Consulta el estado del trabajo.
GetJobResult	GetJobResultRequest	RenderResponse	Unario. Descarga un resultado completado.
GetJobResultStream	GetJobResultRequest	RenderChunk (stream)	Streaming desde el servidor. Descarga un resultado completado como fragmentos.
CancelJob	CancelJobRequest	JobResponse	Unario. Cancela o elimina un trabajo.
CreateSession	CreateSessionRequest	SessionResponse	Unario. Crea una sesión de construcción de documentos.
GetSession	GetSessionRequest	SessionResponse	Unario. Obtiene los metadatos de la sesión.
DestroySession	DestroySessionRequest	DestroySessionResponse	Unario. Destruye una sesión y su documento.
SessionOperation	SessionOperationRequest	SessionResponse	Unario. Ejecuta una operación sobre un documento de sesión.
SessionRender	SessionRenderRequest	RenderResponse	Unario. Renderiza un documento de sesión a PDF.
SessionRenderStream	SessionRenderRequest	RenderChunk (stream)	Streaming desde el servidor. Renderiza un documento de sesión como fragmentos.
ExecuteCapability	CapabilityRequest	CapabilityResponse	Unario. Ejecuta una operación de capacidad controlada por nivel.
GetCapabilities	GetCapabilitiesRequest	GetCapabilitiesResponse	Unario. Enumera las capacidades para el cliente autenticado.
HealthCheck	HealthCheckRequest	HealthCheckResponse	Unario. Sonda de vivacidad.
ReadinessCheck	ReadinessCheckRequest	ReadinessCheckResponse	Unario. Sonda de preparación.

Símbolos de mensaje

Los mensajes de solicitud y respuesta son los símbolos estructurales del esquema. Los mensajes de renderizado —RenderRequest, RenderResponse y el RenderChunk de streaming— transportan el tamaño de página, la orientación, las operaciones ordenadas y los bytes del PDF resultante. Los mensajes de trabajo —SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest y JobResponse— modelan el ciclo de vida del trabajo asíncrono, con sus metadatos incluidos en el mensaje JobData. Los mensajes de sesión —CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest y SessionRenderRequest— modelan el ciclo de vida de la sesión con estado, con sus metadatos incluidos en el mensaje SessionData. Los mensajes de capacidad —CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest y GetCapabilitiesResponse— transportan el despacho y la introspección de operaciones controladas por nivel. Los mensajes del sistema —HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest y ReadinessCheckResponse— transportan el estado de vivacidad y preparación.

Los archivos .proto incluidos son el contrato de comunicación de referencia; la referencia del transporte gRPC está en Transporte gRPC.

Modelo de errores

El servidor informa de los fallos con el mecanismo nativo de errores de cada transporte. Cada transporte conserva la misma condición lógica; solo difiere la codificación.

MCP

Los errores de MCP son objetos de error de JSON-RPC 2.0. Un método desconocido devuelve método-no-encontrado (-32601); un mensaje que no es JSON-RPC válido devuelve solicitud-no-válida (-32600); una entrada que no se puede analizar devuelve error-de-análisis (-32700). Una herramienta que falla devuelve una respuesta JSON-RPC correcta cuyo contenido marca el error, en lugar de un error a nivel de transporte, para que el agente pueda leer el mensaje. Un desafío de confirmación para una herramienta ApprovalRequired también es una respuesta correcta, no un error.

REST

REST usa códigos de estado del protocolo de transferencia de hipertexto (HTTP) con la semántica definida por RFC 9110. Un 200 transporta el resultado; se devuelve un 400 cuando un campo de la solicitud no supera la validación de formato; se devuelve un 401 cuando no se presenta una clave de API válida y se incluye una cabecera de desafío WWW-Authenticate: Bearer; se devuelve un 403 cuando el nivel de una clave válida no autoriza la operación; se devuelve un 404 cuando una ruta controlada por nivel no está registrada porque su paquete está ausente. Los cuerpos de error legibles por máquina son documentos Problem Details según RFC 9457, servidos con el tipo de medio application/problem+json y un identificador uniforme de recursos (URI) type estable por condición. Los fallos de validación a nivel de campo se enumeran en el cuerpo. Como refuerzo contra el path traversal, un document_id que no coincide con el patrón doc_[a-f0-9]{24} se rechaza con 400 antes de que se ejecute la herramienta. La canalización de middleware de REST y la tabla de rutas están documentadas en Transporte REST.

gRPC

gRPC usa códigos de estado estándar de gRPC. Un token ausente, mal formado, desconocido, deshabilitado o caducado hace fallar la llamada con UNAUTHENTICATED, y no con un estado HTTP. El detalle de error enriquecido refleja la forma de los detalles de problema (Problem Details) de REST y se transporta en los detalles de estado de gRPC, de modo que el URI type del error es coherente en todos los transportes.

Consulta también: RFC 9110 (HTTP Semantics) para la semántica de los códigos de estado y RFC 9457 (Problem Details for HTTP APIs) para el formato del cuerpo de error.

• RFC 9110: https://www.rfc-editor.org/rfc/rfc9110
• RFC 9457: https://www.rfc-editor.org/rfc/rfc9457

Límites de tasa y cuotas

El transporte REST aplica limitación de tasa por dirección IP y por cliente en su canalización de middleware, además de límites de tamaño de cuerpo y de payload por nivel y un tiempo de espera por solicitud. Los topes relevantes son valores de configuración, no constantes codificadas:

• Los topes de payload por nivel (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit) y los tiempos de espera correspondientes se aplican en REST según el nivel de la clave autenticada. Consulta Configuración.
• El almacén de documentos en memoria está acotado por max_documents (predeterminado 50) y document_ttl (predeterminado 1800 segundos).
• El estado de límite de tasa e idempotencia es por trabajador, salvo que NEXTPDF_REDIS_HOST esté configurado para un almacén compartido. Consulta Despliegue.

Cuando se comparten los almacenes de límite de tasa e idempotencia, los envíos repetidos e idénticos de trabajos asíncronos se deduplican por el idempotency_key. El transporte MCP gestiona una solicitud a la vez a través de tuberías y deduplica un id de solicitud repetido usando un búfer de 64 entradas, en lugar de aplicar límites de tasa de red.

Notas de desarrollo

• Lee los nombres de herramienta, las clases y los niveles de riesgo desde el código fuente bajo src/Tools/; no asumas un total fijo. Consulta el servidor en ejecución para obtener el recuento autorizado, como se muestra en Catálogo de herramientas.
• Regenera los stubs de cliente de gRPC a partir de los archivos proto/nextpdf/connect/v1/*.proto incluidos; el paquete y el espacio de nombres son nextpdf.connect.v1. No edites a mano las clases de mensaje generadas.
• Una herramienta ApprovalRequired responde con un desafío de confirmación en la primera llamada. Construye la ruta de reintento —transmite el desafío y, a continuación, vuelve a invocar con _confirmation_token— antes de publicar una integración que controle output_pdf o cualquier herramienta de mutación.
• Una ruta o capacidad controlada por nivel que no está instalada no es un fallo de autenticación: REST devuelve 404 para una ruta ausente, y la ExecuteCapability de gRPC informa de la operación como no disponible. Trata la ausencia de un nivel Pro o Enterprise como una operación esperada, no como un fallo.
• Mantén las claves de API fuera del control de versiones; móntalas desde un archivo de secretos y prefiere el almacén de claves de archivo con recarga en caliente para que la rotación no necesite reinicio. Consulta Seguridad y operaciones.

Consulta también

• Guía del desarrollador — arquitectura, ciclo de vida, puntos de extensión y la lista de comprobación de pruebas
• Catálogo de herramientas — el conjunto de herramientas del núcleo verificado y el recuento en tiempo de ejecución
• Niveles de riesgo HITL — el modelo de riesgo y el desafío de confirmación
• Transporte MCP · Transporte REST · Transporte gRPC — detalles de comunicación por transporte
• Seguridad y operaciones — autenticación, seguridad de transporte y el modelo de amenazas