One MCP Server, Three Config Schemas: Wiring PDF4me Into Cursor, VS Code, Claude Desktop, Windsurf and Continue

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.

One command, every client

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.

Three shapes for one declaration

Here is where the copy and paste breaks.

Shape 1: 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"
      }
    }
  }
}

Shape 2: 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.

Shape 3: 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.

The file paths differ too, by client and by OS

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.

The variable is called API_KEY

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.

When uvx is not on the PATH

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.

Run the server without a client at all

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.

Where MCP stops and Agent Skills begins

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.

Two things to confirm before this touches real documents

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