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/mcp | Ospitato: /mcp | |
|---|---|---|
| Dove gira | Sul tuo computer, avviato dal client MCP tramite stdio | Sui server di PDF123 all'indirizzo https://pdf123.xyz/mcp |
| Input | Percorsi di file su disco. Il server li carica e salva il risultato accanto all'input | File inviati tramite lo strumento di caricamento |
| Credenziali | Nessuna per l'uso anonimo. PDFX_API_KEY è facoltativa | Header X-API-KEY a ogni richiesta. Senza, la risposta è 401 |
| Installazione | npx -y @pdf123/mcp | Nessuna. Aggiungi l'URL e l'header al client |
| Strumenti | Cinque strumenti per l'intero catalogo di 97 strumenti | Sette strumenti: describe, convert, pages, misc, security, upload e download |
| Usalo quando | Un agente lavora sui documenti in una cartella locale | Un 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 mcp add pdf123 -- npx -y @pdf123/mcpClaude 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.
{
"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.
| Strumento | Cosa fa | Argomenti principali |
|---|---|---|
pdf123_list_tools | Elenca gli strumenti, una riga ciascuno | group, query, format |
pdf123_describe_tool | Mostra i campi di uno strumento, i valori predefiniti, i valori consentiti e se viene eseguito come lotto | tool |
pdf123_run_tool | Esegue uno strumento sui file locali e restituisce il percorso salvato o il rapporto JSON | tool, files, params, output |
pdf123_run_pipeline | Concatena fino a 8 strumenti in una sola richiesta | steps, files, output |
pdf123_call | Invia 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_passwordapre tutti gli input cifrati.passwordsimposta una password per file, nello stesso ordine difiles, con una stringa vuota per un file aperto. Funziona anche con gli strumenti a più file come Unisci. - Pipeline.
pdf123_run_pipelineaccetta fino a 8 passaggi, e ognuno alimenta il successivo. Accetta gli stessi argomenti per le password. - Chiamate grezze.
pdf123_callraggiunge 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.
idempotencyKeyrestituisce 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.
"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.
{
"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.
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.
{
"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.
Pagine correlate
- Skill per agenti per Claude Code, Codex e Cursor, una per il catalogo e una per ogni strumento
- /llms.txt, un indice in testo semplice degli strumenti, dell'API e dell'endpoint MCP
- Riga di comando pdfx e SDK TypeScript, che condividono il catalogo
- Panoramica per sviluppatori, il documento OpenAPI e Swagger UI
- Pagine degli strumenti: Unisci, Comprimi, OCR, Proteggi, Ripara
- Gli articoli "Built for AI Agents, Not Just Browsers" e "Same Operation, Four Clients" sul blog di PDF123
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.