¿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/mcp | Alojado: /mcp | |
|---|---|---|
| Dónde se ejecuta | En tu equipo, iniciado por el cliente MCP mediante stdio | En los servidores de PDF123, en https://pdf123.xyz/mcp |
| Entrada | Rutas de archivo en disco. El servidor las sube y guarda el resultado junto a la entrada | Archivos enviados con la herramienta de subida |
| Credenciales | Ninguna en uso anónimo. PDFX_API_KEY es opcional | Cabecera X-API-KEY en cada solicitud. Sin ella la respuesta es 401 |
| Instalación | npx -y @pdf123/mcp | Ninguna. Añade la URL y la cabecera al cliente |
| Herramientas | Cinco herramientas para el catálogo completo de 97 | Siete herramientas: describe, convert, pages, misc, security, upload y download |
| Úsalo cuando | Un agente trabaja con documentos de una carpeta local | Un 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 mcp add pdf123 -- npx -y @pdf123/mcpClaude 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.
{
"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.
| Herramienta | Qué hace | Argumentos principales |
|---|---|---|
pdf123_list_tools | Enumera las herramientas, una línea por cada una | group, query, format |
pdf123_describe_tool | Muestra los campos de una herramienta, sus valores por defecto, los valores permitidos y si se ejecuta como lote | tool |
pdf123_run_tool | Ejecuta una herramienta sobre archivos locales y devuelve la ruta guardada o el informe JSON | tool, files, params, output |
pdf123_run_pipeline | Encadena hasta 8 herramientas en una sola solicitud | steps, files, output |
pdf123_call | Enví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_passwordabre todas las entradas cifradas.passwordsdefine una contraseña por archivo, en el mismo orden quefiles, con una cadena vacía para los archivos abiertos. También funciona con herramientas de varios archivos, como Unir. - Pipelines.
pdf123_run_pipelineadmite hasta 8 pasos, y cada paso alimenta al siguiente. Acepta los mismos argumentos de contraseña. - Llamadas sin procesar.
pdf123_callllega 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.
idempotencyKeyreproduce 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.
"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.
{
"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.
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.
{
"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.
Páginas relacionadas
- Skills para agentes para Claude Code, Codex y Cursor: una para el catálogo y otra por herramienta
- /llms.txt, un índice en texto plano de las herramientas, la API y el endpoint MCP
- Línea de comandos pdfx y SDK de TypeScript, que comparten el catálogo
- Resumen para desarrolladores, el documento OpenAPI y Swagger UI
- Páginas de herramientas: Unir, Comprimir, OCR, Proteger, Reparar
- Las entradas «Built for AI Agents, Not Just Browsers» y «Same Operation, Four Clients» del blog de PDF123
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.