Quin servidor MCP he de fer servir?
Tots dos servidors exposen operacions de PDF123. Es diferencien pel lloc on s'executen i per com hi arriben els fitxers.
| Local: @pdf123/mcp | Allotjat: /mcp | |
|---|---|---|
| On s'executa | A la teva màquina, iniciat pel client MCP per stdio | Als servidors de PDF123, a https://pdf123.xyz/mcp |
| Entrada | Rutes de fitxers del disc. El servidor els puja i desa el resultat al costat de l'entrada | Fitxers enviats amb l'eina de pujada |
| Credencials | Cap per a l'ús anònim. PDFX_API_KEY és opcional | Capçalera X-API-KEY a cada petició. Sense ella la resposta és 401 |
| Instal·lació | npx -y @pdf123/mcp | Cap. Afegeix l'URL i la capçalera al client |
| Eines | Cinc eines per a tot el catàleg de 97 eines | Set eines: describe, convert, pages, misc, security, upload i download |
| Fes-lo servir quan | Un agent treballa amb documents d'una carpeta local | Un agent o servei allotjat ja gestiona les pujades amb l'API |
Fes servir el servidor local per als assistents de programació d'un portàtil. Fes servir el punt allotjat quan l'agent s'executa al núvol i no pot llegir el teu disc.
Com instal·lo el servidor MCP local?
No cal instal·lar res, perquè el client MCP inicia el servidor amb npx. A Claude Code, afegeix-lo amb una sola ordre.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop llegeix claude_desktop_config.json i Cursor llegeix .cursor/mcp.json. Altres clients tenen una pàgina o un fitxer de configuració de MCP. Tots accepten la mateixa entrada mcpServers.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Reinicia el client després de canviar-ne la configuració. Per tenir-ne una còpia al teu path, executa npm install -g @pdf123/mcp, que proporciona l'ordre pdf123-mcp. El servidor necessita Node 20.3 o superior i una base d'API accessible. No hi ha mode sense connexió.
Què li demano primer a l'agent?
Demana-ho en llenguatge natural i anomena els fitxers. Per exemple:
Uneix ~/Documents/a.pdf i ~/Documents/b.pdf i després comprimeix el resultat.
L'agent crida pdf123_run_pipeline, o pdf123_run_tool dues vegades, puja els fitxers a PDF123 i respon amb la ruta del fitxer desat. El resultat es desa al costat de la primera entrada i mai no substitueix un fitxer existent. Les mateixes operacions existeixen al lloc web com a Uneix i Comprimeix.
Quines eines ofereix el servidor local?
El servidor té cinc eines. Els identificadors d'eina com merge són arguments de cadena simples, de manera que la llista d'eines es manté petita.
| Eina | Què fa | Arguments clau |
|---|---|---|
pdf123_list_tools | Llista les eines, una línia per eina | group, query, format |
pdf123_describe_tool | Mostra els camps d'una eina, els valors per defecte, els valors permesos i si s'executa com a lot | tool |
pdf123_run_tool | Executa una eina sobre fitxers locals i retorna la ruta desada o l'informe JSON | tool, files, params, output |
pdf123_run_pipeline | Encadena fins a 8 eines en una sola petició | steps, files, output |
pdf123_call | Envia una petició en brut a qualsevol identificador d'eina, identificador d'operació o ruta /api/... | target, files, fields |
Un agent sol cridar pdf123_list_tools per trobar una eina, pdf123_describe_tool per llegir-ne els camps i després pdf123_run_tool. Un identificador mal escrit retorna suggeriments del tipus «volies dir».
Com funcionen els lots, les contrasenyes i els pipelines?
- Lots. Diversos fitxers donats a una eina d'un sol fitxer s'executen com a lot amb un resultat per fitxer. Cada fitxer es desa quan acaba. La resposta és un informe per fitxer. Si algun fitxer falla, la resposta és un error amb l'informe adjunt, de manera que l'agent pot tornar a provar només els fitxers fallits.
- Contrasenyes.
input_passwordobre totes les entrades xifrades.passwordsdefineix una contrasenya per fitxer, en el mateix ordre quefiles, amb una cadena buida per a un fitxer obert. També funciona amb eines de diversos fitxers com Uneix. - Pipelines.
pdf123_run_pipelineaccepta fins a 8 passos, i cada pas alimenta el següent. Accepta els mateixos arguments de contrasenya. - Crides en brut.
pdf123_callarriba a operacions més noves que el servidor. No es valida res en local. - Eines de filtre. Una eina l'identificador de la qual comença per
filter-respon{"matched": false}quan no es compleix la seva condició. És un resultat, no un error. - Reintents.
idempotencyKeyreprodueix el primer resultat durant 24 hores.
Com limito les carpetes que pot fer servir l'agent?
Defineix PDFX_MCP_ROOT amb un directori. Separa diversos directoris amb dos punts, o amb punt i coma a Windows. Aleshores el servidor llegeix les entrades i escriu els resultats només dins d'aquests directoris. Les rutes de fora, els escapaments amb .. i els enllaços simbòlics que surten es rebutgen abans de pujar res, amb Code: path_not_allowed. Sense aquesta variable, es permet qualsevol ruta a la qual pugui arribar el procés del servidor.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Defineix les variables d'entorn al bloc env del client, o amb claude mcp add -e NAME=value. PDFX_API_BASE apunta el servidor al teu propi pdfx-server; consulta Autoallotjament.
Com són els resultats i els errors?
Un resultat únic és un petit objecte JSON amb el path desat, el contentType i la mida en bytes. El resultat d'un lot té processed, unmatched, failed i una llista files. Aquestes formes coincideixen amb pdfx --json a la línia d'ordres. Una eina que retorna un informe, com Informació del document, el retorna en línia.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Una crida fallida torna com a error d'eina. El seu text acaba amb les línies Reason:, Code: i Hint: quan el servidor les ha proporcionat, de manera que l'agent pot bifurcar segons el codi.
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.Si un identificador d'eina té una errada, l'error llista identificadors propers i acaba amb Code: unknown_tool. Una eina que no troba res per retornar, com pdf-to-csv en un PDF sense taules, retorna Code: no_content en lloc d'un fitxer buit. Consulta Codis d'error.
Com faig servir el punt MCP allotjat?
L'API incorpora un servidor MCP a POST https://pdf123.xyz/mcp. Autentica't amb la mateixa capçalera X-API-KEY que fa servir l'API REST. Sense clau, el punt respon 401. Crea una clau a la pàgina per a desenvolupadors.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}El servidor allotjat llista set eines: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload i pdf_toolbox_download. Cada eina de categoria accepta un nom d'operation i els seus paràmetres, a més d'un fitxer o d'un fileId retornat per l'eina de pujada. Fes servir l'eina describe per obtenir l'esquema d'una operació.
Pàgines relacionades
- Skills per a agents per a Claude Code, Codex i Cursor, una per al catàleg i una per eina
- /llms.txt, un índex en text pla de les eines, l'API i el punt MCP
- Línia d'ordres pdfx i SDK de TypeScript, que comparteixen el catàleg
- Visió general per a desenvolupadors, el document OpenAPI i Swagger UI
- Pàgines d'eines: Uneix, Comprimeix, OCR, Protegeix, Repara
- Les entrades «Built for AI Agents, Not Just Browsers» i «Same Operation, Four Clients» al blog de PDF123
FAQ
Què és MCP?
MCP, el Model Context Protocol, és un estàndard obert per connectar clients d'IA amb eines externes. Un client com Claude Code inicia o contacta un servidor MCP, en llista les eines i les crida en nom de la persona usuària.
Funciona el servidor MCP local sense connexió?
No. Puja els fitxers a l'API de PDF123, o al servidor indicat a PDFX_API_BASE, i desa el resultat en local. La base de l'API ha de ser accessible.
Necessita una clau d'API?
El servidor local no necessita clau per a l'ús anònim. Defineix PDFX_API_KEY si el teu servidor en requereix una. El punt allotjat a /mcp sempre necessita una capçalera X-API-KEY.
Pot l'agent llegir qualsevol fitxer del meu ordinador?
Per defecte pot llegir qualsevol ruta a la qual pugui arribar el procés del servidor. Defineix PDFX_MCP_ROOT per limitar les lectures i les escriptures als directoris que triïs.
Què passa amb els meus fitxers?
El servidor local puja cada entrada a l'API de PDF123, o al teu propi servidor, per processar-la. La descripció de l'eina indica que els fitxers s'hi eliminen després del processament. El resultat es desa a la teva màquina. Per als detalls, llegeix la pàgina de privadesa dels fitxers.
Quantes eines pot fer servir un agent?
El servidor local arriba a les 97 eines del catàleg amb cinc eines MCP. El punt allotjat agrupa les operacions per categoria (convert, pages, misc i security) darrere de set eines MCP.