Ir al contenido principal
PPDF123

Servidores MCP de PDF123 para agentes de IA

MCP, el Model Context Protocol, es un estándar abierto que permite a clientes de IA como Claude Code, Claude Desktop y Cursor llamar a herramientas externas. PDF123 ofrece un servidor MCP local, @pdf123/mcp, para los archivos de tu equipo y un endpoint alojado que usa una clave de API.

@pdf123/mcpNode 20.3 o superior

Instalación

npx -y @pdf123/mcp
En esta página

¿Qué servidor MCP debo usar?

Ambos servidores exponen las operaciones de PDF123. Se diferencian en dónde se ejecutan y en cómo les llegan los archivos.

Local: @pdf123/mcpAlojado: /mcp
Dónde se ejecutaEn tu equipo, iniciado por el cliente MCP mediante stdioEn los servidores de PDF123, en https://pdf123.xyz/mcp
EntradaRutas de archivo en disco. El servidor las sube y guarda el resultado junto a la entradaArchivos enviados con la herramienta de subida
CredencialesNinguna en uso anónimo. PDFX_API_KEY es opcionalCabecera X-API-KEY en cada solicitud. Sin ella la respuesta es 401
Instalaciónnpx -y @pdf123/mcpNinguna. Añade la URL y la cabecera al cliente
HerramientasCinco herramientas para el catálogo completo de 97Siete herramientas: describe, convert, pages, misc, security, upload y download
Úsalo cuandoUn agente trabaja con documentos de una carpeta localUn agente o servicio alojado ya gestiona las subidas mediante la API

Usa el servidor local para asistentes de programación en un portátil. Usa el endpoint alojado cuando el agente se ejecute en la nube y no pueda leer tu disco.

¿Cómo instalo el servidor MCP local?

No hace falta instalar nada, porque el cliente MCP inicia el servidor con npx. En Claude Code, añádelo con un solo comando.

Claude Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

Claude Desktop lee claude_desktop_config.json y Cursor lee .cursor/mcp.json. Otros clientes tienen una página o un archivo de ajustes de MCP. Todos aceptan la misma entrada mcpServers.

MCP client configurationjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

Reinicia el cliente después de cambiar su configuración. Para conservar una copia en tu PATH, ejecuta npm install -g @pdf123/mcp, que proporciona el comando pdf123-mcp. El servidor necesita Node 20.3 o superior y una base de API accesible. No existe un modo sin conexión.

¿Qué le pido primero al agente?

Pídelo en lenguaje natural y nombra los archivos. Por ejemplo:

Une ~/Documents/a.pdf y ~/Documents/b.pdf y luego comprime el resultado.

El agente llama a pdf123_run_pipeline, o dos veces a pdf123_run_tool, sube los archivos a PDF123 y responde con la ruta del archivo guardado. El resultado se guarda junto a la primera entrada y nunca reemplaza un archivo existente. Las mismas operaciones existen en el sitio web como Unir y Comprimir.

¿Qué herramientas ofrece el servidor local?

El servidor tiene cinco herramientas. Los ids de herramienta, como merge, son simples argumentos de texto, de modo que la lista de herramientas se mantiene corta.

HerramientaQué haceArgumentos principales
pdf123_list_toolsEnumera las herramientas, una línea por cada unagroup, query, format
pdf123_describe_toolMuestra los campos de una herramienta, sus valores por defecto, los valores permitidos y si se ejecuta como lotetool
pdf123_run_toolEjecuta una herramienta sobre archivos locales y devuelve la ruta guardada o el informe JSONtool, files, params, output
pdf123_run_pipelineEncadena hasta 8 herramientas en una sola solicitudsteps, files, output
pdf123_callEnvía una solicitud sin procesar a cualquier id de herramienta, id de operación o ruta /api/...target, files, fields

Un agente suele llamar a pdf123_list_tools para encontrar una herramienta, a pdf123_describe_tool para leer sus campos y después a pdf123_run_tool. Un id mal escrito devuelve sugerencias de «quizá quisiste decir».

¿Cómo funcionan los lotes, las contraseñas y los pipelines?

  • Lotes. Si das varios archivos a una herramienta de un solo archivo, se ejecutan como un lote con un resultado por archivo. Cada archivo se guarda en cuanto termina. La respuesta es un informe por archivo. Si algún archivo falla, la respuesta es un error con el informe adjunto, para que el agente pueda reintentar solo los archivos fallidos.
  • Contraseñas. input_password abre todas las entradas cifradas. passwords define una contraseña por archivo, en el mismo orden que files, con una cadena vacía para los archivos abiertos. También funciona con herramientas de varios archivos, como Unir.
  • Pipelines. pdf123_run_pipeline admite hasta 8 pasos, y cada paso alimenta al siguiente. Acepta los mismos argumentos de contraseña.
  • Llamadas sin procesar. pdf123_call llega a operaciones más nuevas que el servidor. No se valida nada en local.
  • Herramientas de filtro. Una herramienta cuyo id empieza por filter- responde {"matched": false} cuando no se cumple su condición. Eso es un resultado, no un error.
  • Reintentos. idempotencyKey reproduce el primer resultado durante 24 horas.

¿Cómo limito las carpetas que puede usar el agente?

Define PDFX_MCP_ROOT con un directorio. Separa varios directorios con dos puntos, o con punto y coma en Windows. El servidor lee entradas y escribe resultados solo dentro de esos directorios. Las rutas fuera de ellos, los escapes con .. y los enlaces simbólicos que salen de ellos se rechazan antes de subir nada, con Code: path_not_allowed. Sin esta variable, se permite cualquier ruta a la que llegue el proceso del servidor.

Restrict file accessjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

Define las variables de entorno en el bloque env del cliente, o con claude mcp add -e NAME=value. PDFX_API_BASE apunta el servidor a tu propio pdfx-server; consulta Autohospedaje.

¿Qué aspecto tienen los resultados y los errores?

Un resultado único es un pequeño objeto JSON con la path guardada, el contentType y el tamaño en bytes. El resultado de un lote tiene processed, unmatched, failed y una lista files. Estas estructuras coinciden con pdfx --json en la línea de comandos. Una herramienta que devuelve un informe, como Información del documento, lo devuelve en línea.

Single resultjson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

Una llamada fallida vuelve como error de herramienta. Su texto termina con líneas Reason:, Code: y Hint: cuando el servidor las proporcionó, para que un agente pueda ramificar según el código.

Error texttext
HTTP 400: This PDF is password-protected. Enter its password.
Reason: password_required
Code: bad_request
Hint: Provide the document password, or unlock the PDF first.

Si un id de herramienta tiene una errata, el error enumera ids parecidos y termina con Code: unknown_tool. Una herramienta que no encuentra nada que devolver, como pdf-to-csv con un PDF sin tablas, devuelve Code: no_content en lugar de un archivo vacío. Consulta Códigos de error.

¿Cómo uso el endpoint MCP alojado?

La API incorpora un servidor MCP en POST https://pdf123.xyz/mcp. Autentícate con la misma cabecera X-API-KEY que usa la API REST. Sin clave, el endpoint responde 401. Crea una clave en la página para desarrolladores.

Hosted endpoint configurationjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

El servidor alojado ofrece siete herramientas: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload y pdf_toolbox_download. Cada herramienta de categoría recibe un nombre de operation y sus parámetros, además de un archivo o un fileId devuelto por la herramienta de subida. Usa la herramienta describe para obtener el esquema de una operación.

Preguntas frecuentes

¿Qué es MCP?

MCP, el Model Context Protocol, es un estándar abierto para conectar clientes de IA con herramientas externas. Un cliente como Claude Code inicia un servidor MCP o se conecta a él, enumera sus herramientas y las llama en nombre del usuario.

¿El servidor MCP local funciona sin conexión?

No. Sube los archivos a la API de PDF123, o al servidor indicado en PDFX_API_BASE, y guarda el resultado en local. La base de la API debe ser accesible.

¿Necesita una clave de API?

El servidor local no necesita clave en uso anónimo. Define PDFX_API_KEY si tu servidor la exige. El endpoint alojado en /mcp siempre necesita una cabecera X-API-KEY.

¿Puede el agente leer cualquier archivo de mi ordenador?

Por defecto puede leer cualquier ruta a la que llegue el proceso del servidor. Define PDFX_MCP_ROOT para limitar las lecturas y escrituras a los directorios que elijas.

¿Qué pasa con mis archivos?

El servidor local sube cada entrada a la API de PDF123, o a tu propio servidor, para procesarla. La descripción de la herramienta indica que los archivos se eliminan allí tras el procesamiento. El resultado se guarda en tu equipo. Para más detalles, lee la página de privacidad de archivos.

¿Cuántas herramientas puede usar un agente?

El servidor local llega a las 97 herramientas del catálogo mediante cinco herramientas MCP. El endpoint alojado agrupa sus operaciones por categoría (convert, pages, misc y security) detrás de siete herramientas MCP.