Vilken MCP-server ska jag använda?
Båda servrarna ger tillgång till PDF123:s operationer. De skiljer sig i var de körs och hur filerna når dem.
| Lokal: @pdf123/mcp | Hostad: /mcp | |
|---|---|---|
| Körs var | På din dator, startad av MCP-klienten via stdio | På PDF123:s servrar på https://pdf123.xyz/mcp |
| Indata | Filsökvägar på disken. Servern laddar upp dem och sparar resultatet bredvid indatafilen | Filer som skickas via uppladdningsverktyget |
| Autentiseringsuppgifter | Inga för anonym användning. PDFX_API_KEY är valfri | Rubriken X-API-KEY i varje begäran. Utan den blir svaret 401 |
| Installation | npx -y @pdf123/mcp | Ingen. Lägg till URL:en och rubriken i klienten |
| Verktyg | Fem verktyg för hela katalogen med 97 verktyg | Sju verktyg: describe, convert, pages, misc, security, upload och download |
| Använd den när | En agent arbetar med dokument i en lokal mapp | En agent eller hostad tjänst redan hanterar uppladdningar via API:t |
Använd den lokala servern för kodassistenter på en bärbar dator. Använd den hostade slutpunkten när agenten körs i molnet och inte kan läsa din disk.
Hur installerar jag den lokala MCP-servern?
Inget behöver installeras, eftersom MCP-klienten startar servern med npx. I Claude Code lägger du till den med ett enda kommando.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop läser claude_desktop_config.json och Cursor läser .cursor/mcp.json. Andra klienter har en inställningssida eller en fil för MCP. Alla godtar samma mcpServers-post.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Starta om klienten när du har ändrat dess konfiguration. Om du vill ha en kopia i din sökväg kör du npm install -g @pdf123/mcp, som ger kommandot pdf123-mcp. Servern kräver Node 20.3 eller senare och en nåbar API-bas. Det finns inget offlineläge.
Vad ber jag agenten om först?
Fråga med vanligt språk och ange filerna. Till exempel:
Slå ihop ~/Documents/a.pdf och ~/Documents/b.pdf och komprimera sedan resultatet.
Agenten anropar pdf123_run_pipeline, eller pdf123_run_tool två gånger, laddar upp filerna till PDF123 och svarar med sökvägen till den sparade filen. Resultatet sparas bredvid den första indatafilen och ersätter aldrig en befintlig fil. Samma operationer finns som Slå ihop och Komprimera på webbplatsen.
Vilka verktyg erbjuder den lokala servern?
Servern har fem verktyg. Verktygs-id:n som merge är vanliga strängargument, så verktygslistan hålls kort.
| Verktyg | Vad det gör | Viktiga argument |
|---|---|---|
pdf123_list_tools | Listar verktygen, en rad per verktyg | group, query, format |
pdf123_describe_tool | Visar ett verktygs fält, standardvärden, tillåtna värden och om det körs som batch | tool |
pdf123_run_tool | Kör ett verktyg på lokala filer och returnerar den sparade sökvägen eller JSON-rapporten | tool, files, params, output |
pdf123_run_pipeline | Kedjar upp till 8 verktyg i en och samma begäran | steps, files, output |
pdf123_call | Skickar en rå begäran till ett verktygs-id, ett operations-id eller en /api/...-sökväg | target, files, fields |
En agent anropar vanligtvis pdf123_list_tools för att hitta ett verktyg, pdf123_describe_tool för att läsa dess fält och därefter pdf123_run_tool. Ett felstavat id ger förslag av typen "menade du".
Hur fungerar batchar, lösenord och pipelines?
- Batchar. Flera filer som ges till ett enfilsverktyg körs som en batch med ett resultat per fil. Varje fil sparas så fort den är klar. Svaret är en rapport per fil. Om någon fil misslyckas är svaret ett fel med rapporten bifogad, så agenten kan försöka igen bara med de misslyckade filerna.
- Lösenord.
input_passwordöppnar alla krypterade indatafiler.passwordsanger ett lösenord per fil, i samma ordning somfiles, med en tom sträng för en öppen fil. Det fungerar också för flerfilsverktyg som Slå ihop. - Pipelines.
pdf123_run_pipelinetar upp till 8 steg, och varje steg matar nästa. Den godtar samma lösenordsargument. - Råa anrop.
pdf123_callnår operationer som är nyare än servern. Inget valideras lokalt. - Filterverktyg. Ett verktyg vars id börjar med
filter-svarar{"matched": false}när dess villkor inte uppfylls. Det är ett resultat, inte ett fel. - Nya försök.
idempotencyKeyspelar upp det första resultatet i 24 timmar.
Hur begränsar jag vilka mappar agenten kan använda?
Ange PDFX_MCP_ROOT till en katalog. Separera flera kataloger med kolon, eller med semikolon i Windows. Servern läser då indata och skriver resultat bara inom de katalogerna. Sökvägar utanför dem, undantag med .. och symboliska länkar som leder ut avvisas innan något laddas upp, med Code: path_not_allowed. Utan den här variabeln tillåts varje sökväg som serverprocessen når.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Ange miljövariabler i klientens env-block, eller med claude mcp add -e NAME=value. PDFX_API_BASE pekar i stället servern mot din egen pdfx-server; se Self-host.
Hur ser resultat och fel ut?
Ett enskilt resultat är ett litet JSON-objekt med den sparade sökvägen path, contentType och storleken i bytes. Ett batchresultat har processed, unmatched, failed och en files-lista. Dessa strukturer motsvarar pdfx --json på kommandoraden. Ett verktyg som returnerar en rapport, till exempel Dokumentinfo, returnerar rapporten direkt i svaret.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Ett misslyckat anrop kommer tillbaka som ett verktygsfel. Dess text slutar med raderna Reason:, Code: och Hint: när servern lämnade dem, så en agent kan förgrena på koden.
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.Om ett verktygs-id har ett stavfel listar felet liknande id:n och slutar med Code: unknown_tool. Ett verktyg som inte hittar något att returnera, till exempel pdf-to-csv på en PDF utan tabeller, returnerar Code: no_content i stället för en tom fil. Se Felkoder.
Hur använder jag den hostade MCP-slutpunkten?
API:t har en inbyggd MCP-server på POST https://pdf123.xyz/mcp. Autentisera med samma X-API-KEY-rubrik som REST API:t använder. Utan nyckel svarar slutpunkten 401. Skapa en nyckel på utvecklarsidan.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}Den hostade servern listar sju verktyg: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload och pdf_toolbox_download. Varje kategoriverktyg tar ett operationsnamn i operation och dess parametrar, plus en fil eller ett fileId som uppladdningsverktyget returnerat. Använd describe-verktyget för att hämta schemat för en operation.
Relaterade sidor
- Agent-skills för Claude Code, Codex och Cursor, en för katalogen och en per verktyg
- /llms.txt, ett index i ren text över verktygen, API:t och MCP-slutpunkten
- Kommandoraden pdfx och TypeScript-SDK, som delar katalogen
- Översikt för utvecklare, OpenAPI-dokumentet och Swagger UI
- Verktygssidor: Slå ihop, Komprimera, OCR, Lägg till lösenord, Reparera
- Inläggen "Byggd för AI-agenter, inte bara webbläsare" och "Samma operation, fyra klienter" på PDF123-bloggen
Vanliga frågor
Vad är MCP?
MCP, Model Context Protocol, är en öppen standard för att koppla AI-klienter till externa verktyg. En klient som Claude Code startar eller kontaktar en MCP-server, listar dess verktyg och anropar dem för användarens räkning.
Fungerar den lokala MCP-servern offline?
Nej. Den laddar upp filer till PDF123 API, eller till servern som anges i PDFX_API_BASE, och sparar resultatet lokalt. API-basen måste vara nåbar.
Behöver den en API-nyckel?
Den lokala servern behöver ingen nyckel för anonym användning. Ange PDFX_API_KEY om din server kräver en. Den hostade slutpunkten på /mcp kräver alltid rubriken X-API-KEY.
Kan agenten läsa vilken fil som helst på min dator?
Som standard kan den läsa varje sökväg som serverprocessen når. Ange PDFX_MCP_ROOT för att begränsa läsning och skrivning till de kataloger du väljer.
Vad händer med mina filer?
Den lokala servern laddar upp varje indatafil till PDF123 API, eller till din egen server, för bearbetning. Verktygsbeskrivningen anger att filerna raderas där efter bearbetningen. Resultatet sparas på din dator. Läs sidan om filers integritet för detaljer.
Hur många verktyg kan en agent använda?
Den lokala servern når alla 97 verktyg i katalogen via fem MCP-verktyg. Den hostade slutpunkten grupperar sina operationer efter kategori (convert, pages, misc och security) bakom sju MCP-verktyg.