Which MCP server should I use?
Both servers expose PDF123 operations. They differ in where they run and how files reach them.
| Local: @pdf123/mcp | Hosted: /mcp | |
|---|---|---|
| Runs where | On your machine, started by the MCP client over stdio | On PDF123 servers at https://pdf123.xyz/mcp |
| Input | File paths on disk. The server uploads them and saves the result next to the input | Files sent through the upload tool |
| Credentials | None for anonymous use. PDFX_API_KEY is optional | X-API-KEY header on every request. Without it the answer is 401 |
| Install | npx -y @pdf123/mcp | Nothing. Add the URL and header to the client |
| Tools | Six tools for the full 97-tool catalog | Seven tools: describe, convert, pages, misc, security, upload and download |
| Use it when | An agent works on documents in a local folder | An agent or hosted service already handles uploads through the API |
Use the local server for coding assistants on a laptop. Use the hosted endpoint when the agent runs in the cloud and cannot read your disk.
How do I install the local MCP server?
Nothing needs to be installed, because the MCP client starts the server with npx. In Claude Code, add it with one command.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop reads claude_desktop_config.json, and Cursor reads .cursor/mcp.json. Other clients have an MCP settings page or file. All of them accept the same mcpServers entry.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Restart the client after you change its configuration. To keep a copy on your path, run npm install -g @pdf123/mcp, which provides the pdf123-mcp command. The server needs Node 20.3 or newer and a reachable API base. There is no offline mode.
What do I ask the agent first?
Ask in plain language and name the files. For example:
Merge ~/Documents/a.pdf and ~/Documents/b.pdf, then compress the result.
The agent calls pdf123_run_pipeline, or pdf123_run_tool twice, uploads the files to PDF123, and answers with the path of the saved file. The result is saved next to the first input and never replaces an existing file. The same operations exist as Merge and Compress on the website.
Which tools does the local server offer?
The server has six tools. Tool ids such as merge are plain string arguments, so the tool list stays small.
| Tool | What it does | Key arguments |
|---|---|---|
pdf123_list_tools | Lists the tools, one line each | group, query, format |
pdf123_describe_tool | Shows a tool's fields, defaults, allowed values and whether it runs as a batch | tool |
pdf123_run_tool | Runs one tool on local files and returns the saved path or the JSON report | tool, files, params, output |
pdf123_run_pipeline | Chains up to 8 tools in one request | steps, files, output |
pdf123_call | Sends a raw request to any tool id, operation id or /api/... path | target, files, fields |
pdf123_server_status | Shows the server's version, upload limits, OCR page limit and languages, and the operations that are switched off | none |
An agent usually calls pdf123_list_tools to find a tool, pdf123_describe_tool to read its fields, and then pdf123_run_tool. pdf123_server_status is worth one call before a large upload or an OCR job. A mistyped id returns "did you mean" suggestions.
How do batches, passwords and pipelines work?
- Batches. Several files given to a single-file tool run as a batch with one result per file. Each file is saved as it finishes. The reply is a per-file report. If any file fails, the reply is an error with the report attached, so the agent can retry only the failed files.
- Passwords.
input_passwordopens every encrypted input.passwordssets one password per file, in the same order asfiles, with an empty string for an open file. This also works for multi-file tools such as Merge. - Pipelines.
pdf123_run_pipelinetakes up to 8 steps, and each step feeds the next. It accepts the same password arguments. - Raw calls.
pdf123_callreaches operations that are newer than the server. Nothing is validated locally. - Filter tools. A tool whose id starts with
filter-answers{"matched": false}when its condition does not hold. That is a result, not an error. - Retries.
idempotencyKeyreplays the first result for 24 hours.
How do I limit which folders the agent can use?
Set PDFX_MCP_ROOT to a directory. Separate several directories with a colon, or a semicolon on Windows. The server then reads inputs and writes results only inside those directories. Paths outside them, .. escapes and symbolic links that lead out are refused before anything is uploaded, with Code: path_not_allowed. Without this variable, any path the server process can reach is allowed.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Set environment variables in the client's env block, or with claude mcp add -e NAME=value. PDFX_API_BASE points the server at your own pdfx-server instead; see Self-host.
What do results and errors look like?
A single result is a small JSON object with the saved path, the contentType and the size in bytes. When the service reports something about the result it adds headers and notes, such as the size before and after, whether a Compress target size was met, or how many parts of a split are over the size limit. A batch result has processed, unmatched, failed and a files list. These shapes match pdfx --json on the command line. A tool that returns a report, such as Document info, returns the report inline.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}A failed call comes back as a tool error. Its text ends with Reason:, Code: and Hint: lines when the server supplied them, so an agent can branch on the code.
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.If a tool id has a typo, the error lists close ids and ends with Code: unknown_tool. A tool that finds nothing to return, such as pdf-to-csv on a PDF without tables, returns Code: no_content instead of an empty file. See Error codes.
How do I use the hosted MCP endpoint?
The API embeds an MCP server at POST https://pdf123.xyz/mcp. Authenticate with the same X-API-KEY header that the REST API uses. Without a key the endpoint answers 401. Create a key on the Developers page.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}The hosted server lists seven tools: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload and pdf_toolbox_download. Each category tool takes an operation name and its parameters, plus a file or a fileId returned by the upload tool. Use the describe tool to get the schema of one operation.
Related pages
- Agent skills for Claude Code, Codex and Cursor, one for the catalog and one per tool
- /llms.txt, a plain-text index of the tools, the API and the MCP endpoint
- pdfx command line and TypeScript SDK, which share the catalog
- Developers overview, the OpenAPI document and Swagger UI
- Tool pages: Merge, Compress, OCR, Protect, Repair
- The posts "Built for AI Agents, Not Just Browsers" and "Same Operation, Four Clients" on the PDF123 blog
FAQ
What is MCP?
MCP, the Model Context Protocol, is an open standard for connecting AI clients to external tools. A client such as Claude Code starts or contacts an MCP server, lists its tools, and calls them on the user's behalf.
Does the local MCP server work offline?
No. It uploads files to the PDF123 API, or to the server named in PDFX_API_BASE, and saves the result locally. The API base must be reachable.
Does it need an API key?
The local server does not need a key for anonymous use. Set PDFX_API_KEY if your server requires one. The hosted endpoint at /mcp always needs an X-API-KEY header.
Can the agent read any file on my computer?
By default it can read any path that the server process can reach. Set PDFX_MCP_ROOT to limit reads and writes to the directories you choose.
What happens to my files?
The local server uploads each input to the PDF123 API, or to your own server, for processing. The tool description states that the files are deleted there after processing. The result is saved on your machine. For details, read the file privacy page.
How many tools can an agent use?
The local server reaches all 97 tools in the catalog through six MCP tools. The hosted endpoint groups its operations by category (convert, pages, misc and security) behind seven MCP tools.