Five MCP clients. One server command. Three different config schemas.
That last part is the bit worth knowing before you wire a document API into an agent, because when you get it wrong nothing errors loudly. The server simply does not appear.
Everything below comes from PDF4me's MCP getting started guide, read in full on 16 August 2026.
The server is a single command:
uvx pdf4me-mcp
The guide is explicit that this is shared, and says to use the same server command in all clients. Five clients are named: Cursor, VS Code, Claude Desktop, Windsurf, and Continue, with Continue covering both VS Code and JetBrains.
uvx
ships with UV, so UV is the one prerequisite beyond a PDF4me API key. On Windows that is a PowerShell one-liner, on macOS and Linux it is available through brew, pipx or pip. The UV documentation covers the options. What uvx
buys you is that there is no global package to install and keep updated. The runner fetches and executes the MCP server package on demand.
So far, a five minute setup. For one client, it is.
Here is where the copy and paste breaks.
mcpServers
as an object keyed by server name Cursor, Claude Desktop and Windsurf:
{
"mcpServers": {
"pdf4me-mcp": {
"command": "uvx",
"args": ["pdf4me-mcp"],
"env": {
"API_KEY": "your-api-key-here"
}
}
}
}
servers
, with an explicit transport type
VS Code does not use mcpServers
at all:
{
"servers": {
"pdf4me-mcp-std": {
"type": "stdio",
"command": "uvx",
"args": ["pdf4me-mcp"],
"env": {
"API_KEY": "your-api-key-here"
}
}
}
}
Two differences from shape 1, not one. The property is servers
, and "type": "stdio"
is required.
mcpServers
as an array of named entries Continue keeps the property name and changes the container:
{
"mcpServers": [
{
"name": "pdf4me-mcp",
"command": "uvx",
"args": ["pdf4me-mcp"],
"env": {
"API_KEY": "your-api-key-here"
}
}
]
}
The server name moves inside the entry as a name
field rather than acting as the object key.
One server, one command, three structurally different declarations. None of that is PDF4me's invention, it is the clients disagreeing with each other, but it is the thing most likely to cost you twenty minutes.
| Client | Config file |
|---|---|
| Cursor | ~/.cursor/mcp.json |
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Claude Desktop (Linux) | ~/.config/Claude/claude_desktop_config.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Continue | ~/.continue/config.json |
Worth having the guide open rather than guessing.
Small detail, disproportionate annoyance. The environment variable is API_KEY
. Not PDF4ME_API_KEY
, not PDF4ME_KEY
. All five config blocks pass it the same way, inside an env
object on the server entry.
If you have integrated PDF4me anywhere else, you have probably been sending the key as a Base64 encoded Authorization: Basic
header, which is what Connect to the PDF4me V2 API documents for direct REST calls. Under MCP you do not do that yourself. You hand the raw key to the server through the environment and the server handles the request signing. Worth noticing before you paste an already encoded value into the config and wonder why nothing authenticates.
The most common Windows failure has a documented answer. If uvx
is not on your PATH
, the client cannot resolve the command and the server never starts. Give the full executable path instead of the bare command:
"command": "C:\\Users\\<YourUser>\\.local\\bin\\uvx"
From the client's side this looks the same as any other silent non-start, so check it early.
Fastest way to separate a server problem from a config problem:
uvx pdf4me-mcp
Or with the key supplied inline, when the package is installed locally:
API_KEY=your-api-key-here pdf4me-mcp
If that runs and your editor still shows nothing, the problem is the JSON shape or the file path, not the server. Two minute check that saves a much longer one. It is the same instinct behind PDF4me's interactive API Tester for the REST endpoints: confirm the thing works in isolation before debugging it through three layers.
PDF4me ships two things that sound similar and are not, and the documentation draws the line cleanly enough to borrow. MCP is tool calling: the agent invokes the server, and the server talks to PDF4me. Agent Skills is the other route, where you install a skill so agents know how to write REST API calls themselves. The MCP guide describes that as separate from MCP tool calling, which is the right framing.
The practical difference: with MCP the agent does not need to know what a PDF4me request body looks like, because it is not writing one. With Agent Skills it does, because it is. Which you want depends on whether you would rather the agent call a tool or author a call. They are not competitors and there is no reason a workspace cannot have both.
First, confirm the server is actually registered rather than assuming. The guide's own final step is to open the client, verify the pdf4me-mcp
server is running, and trigger one action from the assistant. Do that with something harmless first.
Second, look at what the server exposes in your own client. This post deliberately does not print a tool list, because the getting started page does not publish one, and a capability list copied from marketing copy is not something to build a workflow on. The source repository is the place to look, and your client's own tool inspector is better still, because it shows what is loaded rather than what is documented.
That second point generalises past MCP. An agent calling your document API is a caller that cannot ask a clarifying question, cannot read a changelog, and will not notice that a tool it used last week now behaves differently. Whatever surface you hand it, the useful discipline is confirming that surface yourself first.
Website: pdf4me.com
Documentation: docs.pdf4me.com
Developer portal: dev.pdf4me.com