One MCP command, three JSON shapes, and a failure mode that never errors

PDF4me's MCP getting started guide, read in full on 16 August 2026, wires a single server command into five clients using three structurally different JSON blocks ^[1][2]. The part that costs time is the failure mode: according to the guide, getting the shape wrong does not error loudly, the server simply does not appear in the client ^[4].

The command is the easy half. It is `uvx pdf4me-mcp`, and the guide says to use that same command in Cursor, VS Code, Claude Desktop, Windsurf and Continue, with Continue covering both VS Code and JetBrains ^[2][3]. `uvx` ships with UV, which is the only prerequisite beyond a PDF4me API key: a PowerShell one-liner on Windows, brew, pipx or pip on macOS and Linux ^[8]. Nothing is installed globally, because the runner fetches and executes the server package on demand ^[9].

Then the JSON diverges. Cursor, Claude Desktop and Windsurf take an `mcpServers` object in which the server name is the key and the entry carries `command`, `args` and `env` ^[5]. VS Code does not use `mcpServers` at all: the property is `servers` and `"type": "stdio"` is required, so that is two changes from the first shape rather than one ^[6]. Continue keeps the `mcpServers` property name but makes it an array, which moves the server name inside the entry as a `name` field ^[7]. Grouped by schema, that is three of the five clients on the first shape and one client each on the other two ^[19].

None of this is PDF4me's doing. The guide is blunt that this is the clients disagreeing with each other, and that it is the detail most likely to cost you twenty minutes ^[20].

Two adjacent traps sit in the same block. The environment variable is `API_KEY`, not `PDF4ME_API_KEY` or `PDF4ME_KEY`, and all five configs pass it inside an `env` object on the server entry ^[10]. If you have integrated PDF4me elsewhere, you have probably been sending the key as a Base64 encoded `Authorization: Basic` header, which is what the Connect to the PDF4me V2 API documentation specifies for direct REST calls; under MCP you hand over the raw key and the server handles the signing ^[11]. Paste an already encoded value and you have bought yourself another quiet failure.

The other trap is Windows PATH. If `uvx` is not on PATH the client cannot resolve the command and the server never starts, which from the client's side looks identical to any other silent non-start ^[12][13]. The documented answer is to give the full executable path instead of the bare command, such as `C:\Users\<YourUser>\.local\bin\uvx` ^[12].

Which is why the isolation check earns its two minutes: run `uvx pdf4me-mcp` in a terminal, or `API_KEY=your-api-key-here pdf4me-mcp` if the package is installed locally ^[14]. If that runs and the editor still shows nothing, the fault is the JSON shape or the file path, not the server ^[14]. 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 ^[15].

One naming distinction is worth keeping straight. MCP is tool calling, where the agent invokes the server and the server talks to PDF4me ^[16]. Agent Skills is a separate route in which you install a skill so agents know how to write REST calls themselves, and the guide frames it as separate from MCP tool calling ^[16]. With MCP the agent never needs to know what a PDF4me request body looks like, because it is not writing one; with Skills it does, and nothing prevents a workspace having both ^[17].

What to watch is registration, not installation. The guide's own final step is to open the client and verify the server is listed rather than assume it is ^[18]. Until clients converge on one schema, the per-client config block is the part of any MCP server's documentation to read rather than skim ^[20].