Naar de hoofdinhoud
PPDF123

PDF123 MCP-servers voor AI-agents

MCP, het Model Context Protocol, is een open standaard waarmee AI-clients zoals Claude Code, Claude Desktop en Cursor externe tools kunnen aanroepen. PDF123 biedt een lokale MCP-server, @pdf123/mcp, voor bestanden op je machine en een gehost eindpunt dat een API-sleutel gebruikt.

@pdf123/mcpNode 20.3 of nieuwer

Installeren

npx -y @pdf123/mcp
Op deze pagina

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/mcpGehost: /mcp
Draait waarOp je eigen machine, gestart door de MCP-client via stdioOp PDF123-servers op https://pdf123.xyz/mcp
InvoerBestandspaden op schijf. De server uploadt ze en slaat het resultaat naast de invoer opBestanden die via de uploadtool worden verstuurd
InloggegevensGeen voor anoniem gebruik. PDFX_API_KEY is optioneelHeader X-API-KEY bij elk verzoek. Zonder header is het antwoord 401
Installatienpx -y @pdf123/mcpNiets. Voeg de URL en de header toe aan de client
ToolsVijf tools voor de volledige catalogus van 97 toolsZeven tools: describe, convert, pages, misc, security, upload en download
Gebruik het wanneerEen agent werkt met documenten in een lokale mapEen 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 Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

Claude 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.

MCP client configurationjson
{
  "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.

ToolWat het doetBelangrijke argumenten
pdf123_list_toolsToont de tools, één regel per toolgroup, query, format
pdf123_describe_toolToont de velden van een tool, standaardwaarden, toegestane waarden en of de tool als batch draaittool
pdf123_run_toolVoert één tool uit op lokale bestanden en geeft het opgeslagen pad of het JSON-rapport terugtool, files, params, output
pdf123_run_pipelineKoppelt maximaal 8 tools in één verzoeksteps, files, output
pdf123_callStuurt een ruw verzoek naar een willekeurige tool-id, bewerkings-id of een /api/...-padtarget, 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_password opent elke versleutelde invoer. passwords stelt één wachtwoord per bestand in, in dezelfde volgorde als files, met een lege tekenreeks voor een open bestand. Dit werkt ook voor tools met meerdere bestanden, zoals Samenvoegen.
  • Pipelines. pdf123_run_pipeline neemt maximaal 8 stappen en elke stap voedt de volgende. Het accepteert dezelfde wachtwoordargumenten.
  • Ruwe aanroepen. pdf123_call bereikt 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. idempotencyKey geeft 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.

Restrict file accessjson
"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.

Single resultjson
{
  "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.

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.

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.

Hosted endpoint configurationjson
{
  "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.

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.