Misma operación, cuatro clientes: navegador, curl, MCP, pdfx
El mismo merge desde cuatro clientes: el formulario del navegador, curl a /api/v1/general/merge-pdfs, MCP en /mcp y pdfx local o --cloud contra tu base de API.
Cuatro clientes parecen cuatro productos, pero comparten un solo catálogo. Tomemos Combinar como la tarea concreta: unir PDF en orden de subida sin rasterizar las páginas a imágenes. El mismo patrón vale para cualquier otra herramienta del catálogo (compress, OCR, convert y el resto): un id de op y cuatro formas de llamarla.
Navegador
Abre /es/merge, añade archivos en el orden que quieras, pulsa Process y descarga. Las herramientas del catálogo no piden cuenta. El bloque «Llámalo desde el código» de la página construye el curl con los mismos campos que envía el formulario, de modo que la interfaz y el contrato HTTP siguen alineados.
Ese bloque no es texto de marketing. Se genera a partir de la definición de herramienta que el portal ya usa para el formulario, y por eso el cambio de nombre de un parámetro aparece en los dos sitios a la vez. Si el formulario acepta el opcional sortType=byFileName, el ejemplo de curl puede llevar el mismo campo.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
Las llamadas anónimas al catálogo no necesitan clave. Las claves de Desarrolladores dan a la automatización una identidad estable (y a los servidores autoalojados, una puerta). OpenAPI está en /v1/openapi.json.
Para trabajos de varios pasos, POST /api/v1/pipeline acepta ops ordenadas en un campo steps (por ejemplo combinar, luego marcar con agua y luego comprimir). Envía Idempotency-Key cuando los reintentos no deban ejecutar el trabajo dos veces; una repetición correcta puede volver con Idempotency-Replayed. Los fallos usan application/problem+json con códigos estables como rate_limited y bad_request (Errores para desarrolladores).
Las respuestas alojadas también anuncian X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; un HTTP 429 incluye Retry-After. Trata esas cabeceras como el presupuesto real, no como una cifra memorizada de un artículo (límites de tasa anónimos).
MCP
Los agentes que hablan Model Context Protocol se conectan a /mcp, descubren la combinación como herramienta y la llaman con la misma historia de clave de API que REST. Documentación: MCP para desarrolladores.
MCP no es un segundo catálogo, sino un protocolo de descubrimiento e invocación sobre las mismas operaciones que enumera OpenAPI. Si una op falta en MCP, es un fallo del servidor, no una hoja de ruta de producto aparte. Combina MCP con /llms.txt cuando quieras un índice de herramientas en prosa antes de que se conecte el cliente.
CLI pdfx
pdf-core local:
pdfx merge a.pdf b.pdf -o merged.pdf
O el mismo servidor que usa el portal:
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
El modo local nunca sube nada; el modo cloud llama a tu URL base con la misma forma multipart que curl. La skill para agentes de código de dist/skills/pdf-toolbox/SKILL.md documenta las mismas formas de combinación y pipeline, para que los agentes no inventen un segundo OpenAPI.
El OCR a través de cualquiera de estos clientes sigue devolviendo Markdown desde /api/v1/misc/ocr-pdf, no una capa de texto oculta. Ese hecho forma parte del contrato compartido: cambiar el tipo de retorno en un cliente sin cambiar los demás rompería la promesa de «la misma op». Compress sigue en /api/v1/misc/compress-pdf para la recompresión de streams; es una op distinta de la combinación, y se llega a ella de las mismas cuatro formas.
Por qué importa la igualdad
Si la combinación del navegador y la de la API divergieran, las automatizaciones se degradarían en silencio mientras la página de demostración seguiría viéndose bien. Una op y cuatro manejadores es justamente el objetivo. El portal es un cliente de comodidad, no una segunda implementación de combinación, compresión u OCR.
Por eso tampoco hay una versión de escritorio: un quinto árbol de interfaz recrearía el problema de la deriva bajo otro nombre de binario. Para el marco más amplio, consulta Hecho para agentes de IA, no solo navegadores. Sobre la decisión de escritorio, consulta Por qué nos saltamos la app de escritorio. Para levantar la API en tu red, consulta Self-host.