Quel serveur MCP choisir ?
Les deux serveurs exposent les opérations de PDF123. Ils diffèrent par l'endroit où ils s'exécutent et par la manière dont les fichiers leur parviennent.
| Local : @pdf123/mcp | Hébergé : /mcp | |
|---|---|---|
| S'exécute | Sur votre machine, lancé par le client MCP via stdio | Sur les serveurs PDF123, à https://pdf123.xyz/mcp |
| Entrée | Chemins de fichiers sur le disque. Le serveur les envoie et enregistre le résultat à côté du fichier d'entrée | Fichiers transmis par l'outil d'envoi |
| Identifiants | Aucun en usage anonyme. PDFX_API_KEY est facultative | En-tête X-API-KEY à chaque requête. Sans lui, la réponse est 401 |
| Installation | npx -y @pdf123/mcp | Aucune. Ajoutez l'URL et l'en-tête au client |
| Outils | Cinq outils pour tout le catalogue de 97 outils | Sept outils : describe, convert, pages, misc, security, upload et download |
| À utiliser quand | Un agent travaille sur des documents d'un dossier local | Un agent ou un service hébergé gère déjà les envois via l'API |
Utilisez le serveur local pour les assistants de code sur un ordinateur portable. Utilisez le point de terminaison hébergé quand l'agent s'exécute dans le cloud et ne peut pas lire votre disque.
Comment installer le serveur MCP local ?
Rien n'est à installer, car le client MCP lance le serveur avec npx. Dans Claude Code, ajoutez-le avec une seule commande.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop lit claude_desktop_config.json et Cursor lit .cursor/mcp.json. Les autres clients ont une page ou un fichier de réglages MCP. Tous acceptent la même entrée mcpServers.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Redémarrez le client après avoir modifié sa configuration. Pour garder une copie dans votre PATH, lancez npm install -g @pdf123/mcp, qui fournit la commande pdf123-mcp. Le serveur exige Node 20.3 ou plus récent et une base d'API joignable. Il n'existe pas de mode hors ligne.
Que demander en premier à l'agent ?
Demandez en langage courant et nommez les fichiers. Par exemple :
Fusionne ~/Documents/a.pdf et ~/Documents/b.pdf, puis compresse le résultat.
L'agent appelle pdf123_run_pipeline, ou pdf123_run_tool deux fois, envoie les fichiers à PDF123 et répond avec le chemin du fichier enregistré. Le résultat est enregistré à côté de la première entrée et ne remplace jamais un fichier existant. Les mêmes opérations existent sous les noms Fusionner et Compresser sur le site.
Quels outils le serveur local propose-t-il ?
Le serveur a cinq outils. Les identifiants d'outils comme merge sont de simples arguments de type chaîne, ce qui garde la liste d'outils courte.
| Outil | Fonction | Arguments principaux |
|---|---|---|
pdf123_list_tools | Liste les outils, une ligne chacun | group, query, format |
pdf123_describe_tool | Affiche les champs d'un outil, ses valeurs par défaut, ses valeurs autorisées et s'il fonctionne par lots | tool |
pdf123_run_tool | Lance un outil sur des fichiers locaux et renvoie le chemin enregistré ou le rapport JSON | tool, files, params, output |
pdf123_run_pipeline | Enchaîne jusqu'à 8 outils en une seule requête | steps, files, output |
pdf123_call | Envoie une requête brute à n'importe quel identifiant d'outil, d'opération ou chemin /api/... | target, files, fields |
Un agent appelle généralement pdf123_list_tools pour trouver un outil, pdf123_describe_tool pour lire ses champs, puis pdf123_run_tool. Un identifiant mal saisi renvoie des suggestions « vouliez-vous dire ».
Comment fonctionnent les lots, les mots de passe et les pipelines ?
- Lots. Plusieurs fichiers donnés à un outil à fichier unique s'exécutent en lot, avec un résultat par fichier. Chaque fichier est enregistré dès qu'il est terminé. La réponse est un rapport par fichier. Si un fichier échoue, la réponse est une erreur accompagnée du rapport, de sorte que l'agent puisse relancer uniquement les fichiers en échec.
- Mots de passe.
input_passwordouvre toutes les entrées chiffrées.passwordsdéfinit un mot de passe par fichier, dans le même ordre quefiles, avec une chaîne vide pour un fichier ouvert. Cela fonctionne aussi pour les outils multifichiers comme Fusionner. - Pipelines.
pdf123_run_pipelineaccepte jusqu'à 8 étapes, chacune alimentant la suivante. Il accepte les mêmes arguments de mot de passe. - Appels bruts.
pdf123_callatteint les opérations plus récentes que le serveur. Rien n'est validé en local. - Outils de filtre. Un outil dont l'identifiant commence par
filter-répond{"matched": false}quand sa condition n'est pas remplie. C'est un résultat, pas une erreur. - Nouvelles tentatives.
idempotencyKeyrejoue le premier résultat pendant 24 heures.
Comment limiter les dossiers accessibles à l'agent ?
Définissez PDFX_MCP_ROOT sur un répertoire. Séparez plusieurs répertoires par un deux-points, ou par un point-virgule sous Windows. Le serveur ne lit alors les entrées et n'écrit les résultats que dans ces répertoires. Les chemins extérieurs, les échappements par .. et les liens symboliques qui sortent de ces répertoires sont refusés avant tout envoi, avec Code: path_not_allowed. Sans cette variable, tout chemin que le processus du serveur peut atteindre est autorisé.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Définissez les variables d'environnement dans le bloc env du client, ou avec claude mcp add -e NAME=value. PDFX_API_BASE oriente plutôt le serveur vers votre propre pdfx-server ; voir Auto-hébergement.
À quoi ressemblent les résultats et les erreurs ?
Un résultat unique est un petit objet JSON avec le path enregistré, le contentType et la taille en bytes. Le résultat d'un lot contient processed, unmatched, failed et une liste files. Ces formats correspondent à pdfx --json dans la ligne de commande. Un outil qui renvoie un rapport, comme Infos du document, renvoie ce rapport directement dans la réponse.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Un appel en échec revient sous forme d'erreur d'outil. Son texte se termine par des lignes Reason:, Code: et Hint: quand le serveur les a fournies, afin qu'un agent puisse se brancher sur le code.
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 identifiant d'outil contient une faute de frappe, l'erreur liste des identifiants proches et se termine par Code: unknown_tool. Un outil qui n'a rien à renvoyer, comme pdf-to-csv sur un PDF sans tableau, renvoie Code: no_content au lieu d'un fichier vide. Voir Codes d'erreur.
Comment utiliser le point de terminaison MCP hébergé ?
L'API intègre un serveur MCP à POST https://pdf123.xyz/mcp. Authentifiez-vous avec le même en-tête X-API-KEY que celui de l'API REST. Sans clé, le point de terminaison répond 401. Créez une clé sur la page Développeurs.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}Le serveur hébergé liste sept outils : pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload et pdf_toolbox_download. Chaque outil de catégorie prend un nom d'operation et ses paramètres, plus un fichier ou un fileId renvoyé par l'outil d'envoi. Utilisez l'outil describe pour obtenir le schéma d'une opération.
Pages associées
- Skills pour agents pour Claude Code, Codex et Cursor : une pour le catalogue et une par outil
- /llms.txt, un index en texte brut des outils, de l'API et du point de terminaison MCP
- Ligne de commande pdfx et SDK TypeScript, qui partagent le catalogue
- Présentation pour développeurs, le document OpenAPI et Swagger UI
- Pages d'outils : Fusionner, Compresser, OCR, Protéger, Réparer
- Les articles « Built for AI Agents, Not Just Browsers » et « Same Operation, Four Clients » du blog PDF123
FAQ
Qu'est-ce que MCP ?
MCP, le Model Context Protocol, est un standard ouvert pour connecter des clients IA à des outils externes. Un client comme Claude Code lance un serveur MCP ou le contacte, liste ses outils et les appelle au nom de l'utilisateur.
Le serveur MCP local fonctionne-t-il hors ligne ?
Non. Il envoie les fichiers à l'API PDF123, ou au serveur indiqué dans PDFX_API_BASE, et enregistre le résultat en local. La base de l'API doit être joignable.
Faut-il une clé d'API ?
Le serveur local n'exige pas de clé en usage anonyme. Définissez PDFX_API_KEY si votre serveur en exige une. Le point de terminaison hébergé sur /mcp exige toujours un en-tête X-API-KEY.
L'agent peut-il lire n'importe quel fichier de mon ordinateur ?
Par défaut, il peut lire tout chemin que le processus du serveur peut atteindre. Définissez PDFX_MCP_ROOT pour limiter la lecture et l'écriture aux répertoires de votre choix.
Que deviennent mes fichiers ?
Le serveur local envoie chaque entrée à l'API PDF123, ou à votre propre serveur, pour traitement. La description de l'outil indique que les fichiers y sont supprimés après le traitement. Le résultat est enregistré sur votre machine. Pour plus de détails, lisez la page sur la confidentialité des fichiers.
Combien d'outils un agent peut-il utiliser ?
Le serveur local donne accès aux 97 outils du catalogue à travers cinq outils MCP. Le point de terminaison hébergé regroupe ses opérations par catégorie (convert, pages, misc et security) derrière sept outils MCP.