Vai al contenuto principale
PPDF123

I server MCP di PDF123 per agenti IA

MCP, il Model Context Protocol, è uno standard aperto che permette ai client IA come Claude Code, Claude Desktop e Cursor di richiamare strumenti esterni. PDF123 offre un server MCP locale, @pdf123/mcp, per i file sul tuo computer e un endpoint ospitato che usa una chiave API.

@pdf123/mcpNode 20.3 o successivo

Installazione

npx -y @pdf123/mcp
In questa pagina

Quale server MCP devo usare?

Entrambi i server espongono le operazioni di PDF123. Cambiano il luogo in cui girano e il modo in cui i file li raggiungono.

Locale: @pdf123/mcpOspitato: /mcp
Dove giraSul tuo computer, avviato dal client MCP tramite stdioSui server di PDF123 all'indirizzo https://pdf123.xyz/mcp
InputPercorsi di file su disco. Il server li carica e salva il risultato accanto all'inputFile inviati tramite lo strumento di caricamento
CredenzialiNessuna per l'uso anonimo. PDFX_API_KEY è facoltativaHeader X-API-KEY a ogni richiesta. Senza, la risposta è 401
Installazionenpx -y @pdf123/mcpNessuna. Aggiungi l'URL e l'header al client
StrumentiCinque strumenti per l'intero catalogo di 97 strumentiSette strumenti: describe, convert, pages, misc, security, upload e download
Usalo quandoUn agente lavora sui documenti in una cartella localeUn agente o un servizio ospitato gestisce già i caricamenti tramite l'API

Usa il server locale per gli assistenti di programmazione su un portatile. Usa l'endpoint ospitato quando l'agente gira nel cloud e non può leggere il tuo disco.

Come installo il server MCP locale?

Non serve installare nulla, perché è il client MCP ad avviare il server con npx. In Claude Code si aggiunge con un solo comando.

Claude Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

Claude Desktop legge claude_desktop_config.json, e Cursor legge .cursor/mcp.json. Gli altri client hanno una pagina o un file per le impostazioni MCP. Tutti accettano la stessa voce mcpServers.

MCP client configurationjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

Riavvia il client dopo aver modificato la sua configurazione. Per tenerne una copia nel tuo path, esegui npm install -g @pdf123/mcp, che fornisce il comando pdf123-mcp. Il server richiede Node 20.3 o successivo e una base dell'API raggiungibile. Non esiste una modalità offline.

Che cosa chiedo per prima cosa all'agente?

Chiedi in linguaggio naturale e indica i file. Per esempio:

Unisci ~/Documents/a.pdf e ~/Documents/b.pdf, poi comprimi il risultato.

L'agente chiama pdf123_run_pipeline, oppure pdf123_run_tool due volte, carica i file su PDF123 e risponde con il percorso del file salvato. Il risultato viene salvato accanto al primo input e non sostituisce mai un file esistente. Le stesse operazioni esistono sul sito web come Unisci e Comprimi.

Quali strumenti offre il server locale?

Il server ha cinque strumenti. Gli id degli strumenti, come merge, sono semplici argomenti di tipo stringa, quindi l'elenco degli strumenti resta breve.

StrumentoCosa faArgomenti principali
pdf123_list_toolsElenca gli strumenti, una riga ciascunogroup, query, format
pdf123_describe_toolMostra i campi di uno strumento, i valori predefiniti, i valori consentiti e se viene eseguito come lottotool
pdf123_run_toolEsegue uno strumento sui file locali e restituisce il percorso salvato o il rapporto JSONtool, files, params, output
pdf123_run_pipelineConcatena fino a 8 strumenti in una sola richiestasteps, files, output
pdf123_callInvia una richiesta grezza a qualsiasi id di strumento, id di operazione o percorso /api/...target, files, fields

Di solito un agente chiama pdf123_list_tools per trovare uno strumento, pdf123_describe_tool per leggerne i campi e poi pdf123_run_tool. Un id scritto male restituisce suggerimenti del tipo "intendevi".

Come funzionano lotti, password e pipeline?

  • Lotti. Più file passati a uno strumento a file singolo vengono eseguiti come lotto, con un risultato per file. Ogni file viene salvato appena termina. La risposta è un rapporto per file. Se un file fallisce, la risposta è un errore con il rapporto allegato, così l'agente può ritentare solo i file falliti.
  • Password. input_password apre tutti gli input cifrati. passwords imposta una password per file, nello stesso ordine di files, con una stringa vuota per un file aperto. Funziona anche con gli strumenti a più file come Unisci.
  • Pipeline. pdf123_run_pipeline accetta fino a 8 passaggi, e ognuno alimenta il successivo. Accetta gli stessi argomenti per le password.
  • Chiamate grezze. pdf123_call raggiunge le operazioni più recenti del server. In locale non viene validato nulla.
  • Strumenti di filtro. Uno strumento il cui id inizia con filter- risponde {"matched": false} quando la sua condizione non è soddisfatta. È un risultato, non un errore.
  • Nuovi tentativi. idempotencyKey restituisce di nuovo il primo risultato per 24 ore.

Come limito le cartelle che l'agente può usare?

Imposta PDFX_MCP_ROOT su una cartella. Separa più cartelle con i due punti, oppure con il punto e virgola su Windows. Il server legge allora gli input e scrive i risultati solo all'interno di quelle cartelle. I percorsi esterni, le uscite con .. e i collegamenti simbolici che portano fuori vengono rifiutati prima di caricare qualsiasi cosa, con Code: path_not_allowed. Senza questa variabile è consentito qualsiasi percorso raggiungibile dal processo del server.

Restrict file accessjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

Imposta le variabili d'ambiente nel blocco env del client, oppure con claude mcp add -e NAME=value. PDFX_API_BASE punta invece il server al tuo pdfx-server; vedi Self-host.

Che aspetto hanno risultati ed errori?

Un singolo risultato è un piccolo oggetto JSON con il path salvato, il contentType e la dimensione in bytes. Il risultato di un lotto ha processed, unmatched, failed e un elenco files. Queste forme corrispondono a pdfx --json nella riga di comando. Uno strumento che restituisce un rapporto, come Info documento, lo restituisce direttamente nella risposta.

Single resultjson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

Una chiamata fallita torna come errore dello strumento. Il suo testo termina con le righe Reason:, Code: e Hint: quando il server le ha fornite, così un agente può ramificare in base al codice.

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.

Se un id di strumento contiene un errore di battitura, l'errore elenca gli id simili e termina con Code: unknown_tool. Uno strumento che non trova nulla da restituire, come pdf-to-csv su un PDF senza tabelle, restituisce Code: no_content invece di un file vuoto. Vedi Codici di errore.

Come uso l'endpoint MCP ospitato?

L'API incorpora un server MCP all'indirizzo POST https://pdf123.xyz/mcp. Autenticati con lo stesso header X-API-KEY usato dall'API REST. Senza chiave l'endpoint risponde 401. Crea una chiave nella pagina per sviluppatori.

Hosted endpoint configurationjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

Il server ospitato elenca sette strumenti: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload e pdf_toolbox_download. Ogni strumento di categoria accetta il nome di un'operation e i relativi parametri, più un file o un fileId restituito dallo strumento di caricamento. Usa lo strumento describe per ottenere lo schema di una singola operazione.

FAQ

Che cos'è MCP?

MCP, il Model Context Protocol, è uno standard aperto per collegare i client IA a strumenti esterni. Un client come Claude Code avvia o contatta un server MCP, ne elenca gli strumenti e li richiama per conto dell'utente.

Il server MCP locale funziona offline?

No. Carica i file sull'API di PDF123, o sul server indicato in PDFX_API_BASE, e salva il risultato in locale. La base dell'API deve essere raggiungibile.

Serve una chiave API?

Il server locale non richiede una chiave per l'uso anonimo. Imposta PDFX_API_KEY se il tuo server ne richiede una. L'endpoint ospitato su /mcp richiede sempre un header X-API-KEY.

L'agente può leggere qualsiasi file sul mio computer?

Per impostazione predefinita può leggere qualsiasi percorso raggiungibile dal processo del server. Imposta PDFX_MCP_ROOT per limitare letture e scritture alle cartelle che scegli.

Che cosa succede ai miei file?

Il server locale carica ogni input sull'API di PDF123, o sul tuo server, per elaborarlo. La descrizione dello strumento afferma che i file vengono eliminati lì dopo l'elaborazione. Il risultato viene salvato sul tuo computer. Per i dettagli, leggi la pagina sulla privacy dei file.

Quanti strumenti può usare un agente?

Il server locale raggiunge tutti i 97 strumenti del catalogo attraverso cinque strumenti MCP. L'endpoint ospitato raggruppa le sue operazioni per categoria (convert, pages, misc e security) dietro sette strumenti MCP.