Welke MCP-server moet ik gebruiken?
Beide servers bieden PDF123-bewerkingen aan. Ze verschillen in waar ze draaien en hoe bestanden erbij komen.
| Lokaal: @pdf123/mcp | Gehost: /mcp | |
|---|---|---|
| Draait waar | Op je eigen machine, gestart door de MCP-client via stdio | Op PDF123-servers op https://pdf123.xyz/mcp |
| Invoer | Bestandspaden op schijf. De server uploadt ze en slaat het resultaat naast de invoer op | Bestanden die via de uploadtool worden verstuurd |
| Inloggegevens | Geen voor anoniem gebruik. PDFX_API_KEY is optioneel | Header X-API-KEY bij elk verzoek. Zonder header is het antwoord 401 |
| Installatie | npx -y @pdf123/mcp | Niets. Voeg de URL en de header toe aan de client |
| Tools | Vijf tools voor de volledige catalogus van 97 tools | Zeven tools: describe, convert, pages, misc, security, upload en download |
| Gebruik het wanneer | Een agent werkt met documenten in een lokale map | Een agent of gehoste dienst al uploads via de API afhandelt |
Gebruik de lokale server voor codeerassistenten op een laptop. Gebruik het gehoste eindpunt wanneer de agent in de cloud draait en je schijf niet kan lezen.
Hoe installeer ik de lokale MCP-server?
Er hoeft niets te worden geïnstalleerd, want de MCP-client start de server met npx. In Claude Code voeg je hem toe met één opdracht.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop leest claude_desktop_config.json en Cursor leest .cursor/mcp.json. Andere clients hebben een MCP-instellingenpagina of -bestand. Ze accepteren allemaal hetzelfde mcpServers-item.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Start de client opnieuw nadat je de configuratie hebt gewijzigd. Wil je een kopie in je zoekpad houden, voer dan npm install -g @pdf123/mcp uit, wat de opdracht pdf123-mcp oplevert. De server vereist Node 20.3 of nieuwer en een bereikbare API-basis. Er is geen offlinemodus.
Wat vraag ik de agent als eerste?
Vraag het in gewone taal en noem de bestanden. Bijvoorbeeld:
Voeg ~/Documents/a.pdf en ~/Documents/b.pdf samen en comprimeer daarna het resultaat.
De agent roept pdf123_run_pipeline aan, of twee keer pdf123_run_tool, uploadt de bestanden naar PDF123 en antwoordt met het pad van het opgeslagen bestand. Het resultaat wordt naast de eerste invoer opgeslagen en vervangt nooit een bestaand bestand. Dezelfde bewerkingen bestaan op de website als Samenvoegen en Comprimeren.
Welke tools biedt de lokale server?
De server heeft vijf tools. Tool-id's zoals merge zijn gewone tekenreeksargumenten, zodat de lijst met tools klein blijft.
| Tool | Wat het doet | Belangrijke argumenten |
|---|---|---|
pdf123_list_tools | Toont de tools, één regel per tool | group, query, format |
pdf123_describe_tool | Toont de velden van een tool, standaardwaarden, toegestane waarden en of de tool als batch draait | tool |
pdf123_run_tool | Voert één tool uit op lokale bestanden en geeft het opgeslagen pad of het JSON-rapport terug | tool, files, params, output |
pdf123_run_pipeline | Koppelt maximaal 8 tools in één verzoek | steps, files, output |
pdf123_call | Stuurt een ruw verzoek naar een willekeurige tool-id, bewerkings-id of een /api/...-pad | target, files, fields |
Een agent roept meestal pdf123_list_tools aan om een tool te vinden, pdf123_describe_tool om de velden te lezen en daarna pdf123_run_tool. Bij een id met een typefout krijg je suggesties in de trant van "bedoelde je".
Hoe werken batches, wachtwoorden en pipelines?
- Batches. Meerdere bestanden die aan een tool voor één bestand worden gegeven, draaien als batch met één resultaat per bestand. Elk bestand wordt opgeslagen zodra het klaar is. Het antwoord is een rapport per bestand. Als een bestand mislukt, is het antwoord een fout met het rapport als bijlage, zodat de agent alleen de mislukte bestanden opnieuw kan proberen.
- Wachtwoorden.
input_passwordopent elke versleutelde invoer.passwordsstelt één wachtwoord per bestand in, in dezelfde volgorde alsfiles, met een lege tekenreeks voor een open bestand. Dit werkt ook voor tools met meerdere bestanden, zoals Samenvoegen. - Pipelines.
pdf123_run_pipelineneemt maximaal 8 stappen en elke stap voedt de volgende. Het accepteert dezelfde wachtwoordargumenten. - Ruwe aanroepen.
pdf123_callbereikt bewerkingen die nieuwer zijn dan de server. Lokaal wordt niets gevalideerd. - Filtertools. Een tool waarvan de id met
filter-begint, antwoordt{"matched": false}wanneer zijn voorwaarde niet geldt. Dat is een resultaat, geen fout. - Opnieuw proberen.
idempotencyKeygeeft 24 uur lang het eerste resultaat terug.
Hoe beperk ik welke mappen de agent mag gebruiken?
Stel PDFX_MCP_ROOT in op een map. Scheid meerdere mappen met een dubbele punt, of met een puntkomma op Windows. De server leest invoer en schrijft resultaten dan alleen binnen die mappen. Paden daarbuiten, ontsnappingen met .. en symbolische koppelingen die naar buiten leiden, worden geweigerd voordat er iets wordt geüpload, met Code: path_not_allowed. Zonder deze variabele is elk pad toegestaan dat het serverproces kan bereiken.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Stel omgevingsvariabelen in via het env-blok van de client, of met claude mcp add -e NAME=value. PDFX_API_BASE richt de server op je eigen pdfx-server; zie Self-host.
Hoe zien resultaten en fouten eruit?
Een enkel resultaat is een klein JSON-object met het opgeslagen path, het contentType en de grootte in bytes. Een batchresultaat heeft processed, unmatched, failed en een lijst files. Deze vormen komen overeen met pdfx --json op de opdrachtregel. Een tool die een rapport teruggeeft, zoals Documentinfo, geeft het rapport direct terug.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Een mislukte aanroep komt terug als toolfout. De tekst eindigt met regels Reason:, Code: en Hint: wanneer de server die heeft meegegeven, zodat een agent op de code kan vertakken.
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.Bevat een tool-id een typefout, dan toont de fout vergelijkbare id's en eindigt met Code: unknown_tool. Een tool die niets heeft om terug te geven, zoals pdf-to-csv bij een PDF zonder tabellen, geeft Code: no_content terug in plaats van een leeg bestand. Zie Foutcodes.
Hoe gebruik ik het gehoste MCP-eindpunt?
De API heeft een ingebouwde MCP-server op POST https://pdf123.xyz/mcp. Authenticeer met dezelfde header X-API-KEY als de REST API. Zonder sleutel antwoordt het eindpunt met 401. Maak een sleutel aan op de pagina voor ontwikkelaars.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}De gehoste server toont zeven tools: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload en pdf_toolbox_download. Elke categorietool neemt een operation-naam en de bijbehorende parameters, plus een bestand of een fileId die de uploadtool teruggeeft. Gebruik de describe-tool om het schema van één bewerking op te halen.
Gerelateerde pagina's
- Agent-skills voor Claude Code, Codex en Cursor, een voor de catalogus en een per tool
- /llms.txt, een index in platte tekst van de tools, de API en het MCP-eindpunt
- pdfx-opdrachtregel en TypeScript-SDK, die de catalogus delen
- Overzicht voor ontwikkelaars, het OpenAPI-document en Swagger UI
- Toolpagina's: Samenvoegen, Comprimeren, OCR, Beveiligen, Repareren
- De posts "Built for AI Agents, Not Just Browsers" en "Same Operation, Four Clients" op de PDF123-blog
FAQ
Wat is MCP?
MCP, het Model Context Protocol, is een open standaard om AI-clients met externe tools te verbinden. Een client zoals Claude Code start een MCP-server of maakt er contact mee, vraagt de tools op en roept ze namens de gebruiker aan.
Werkt de lokale MCP-server offline?
Nee. Hij uploadt bestanden naar de PDF123-API, of naar de server die in PDFX_API_BASE staat, en slaat het resultaat lokaal op. De API-basis moet bereikbaar zijn.
Heeft hij een API-sleutel nodig?
De lokale server heeft voor anoniem gebruik geen sleutel nodig. Stel PDFX_API_KEY in als je server er een vereist. Het gehoste eindpunt op /mcp vereist altijd een header X-API-KEY.
Kan de agent elk bestand op mijn computer lezen?
Standaard kan hij elk pad lezen dat het serverproces kan bereiken. Stel PDFX_MCP_ROOT in om lezen en schrijven te beperken tot de mappen die je kiest.
Wat gebeurt er met mijn bestanden?
De lokale server uploadt elke invoer voor verwerking naar de PDF123-API, of naar je eigen server. In de toolbeschrijving staat dat de bestanden daar na de verwerking worden verwijderd. Het resultaat wordt op je machine opgeslagen. Lees de pagina over bestandsprivacy voor details.
Hoeveel tools kan een agent gebruiken?
De lokale server bereikt alle 97 tools in de catalogus via vijf MCP-tools. Het gehoste eindpunt groepeert zijn bewerkingen per categorie (convert, pages, misc en security) achter zeven MCP-tools.