# MCP server

> For AI agents: a documentation index is available at https://makespdf.com/llms.txt — every docs page also has a markdown twin (append .md to the page URL), including this one: https://makespdf.com/docs/mcp.md

makesPDF exposes its authoring loop as a
[Model Context Protocol](https://modelcontextprotocol.io/) server at
`https://makespdf.com/api/v1/mcp`. Register it once with your AI client and the assistant
gets schema-validated tools for validating, previewing, and saving DSL templates
— no need to teach it the REST API shape by hand.

## When to use MCP vs the skill

The MCP server and the [skill file](https://makespdf.com/docs/ai-setup) are complementary —
both end up in the AI's context, but they answer different questions.

- **Skill file** — teaches the AI the DSL itself: function reference, style
  properties, design principles, recipes. The skill stays the canonical DSL guide
  regardless of how the AI calls the API.
- **MCP server** — gives the AI schema-validated tools to validate/render/persist
  templates, so it stops guessing request shapes. Also exposes the skill file as
  a fetchable resource, so agents that prefer resources over system prompts can
  pull it on demand.

If your AI client supports remote MCP, use MCP. If it doesn't (or you'd rather
paste the skill URL into a chat), the skill-only flow still works — see
[Bring your own AI](https://makespdf.com/docs/ai-setup).

## Tools exposed

v1 covers the full authoring → render loop. Authoring tools (validate, preview,
template CRUD) are free; the two billed tools are `render_template`, which
produces a real PDF from a saved template and charges credits like
`/api/v1/render`, and `render_markdown`, which does the same for markdown at the
same rate. There is no free markdown preview — markdown needs no layout
iteration, so `render_markdown` is the only markdown render tool.

Both billed renders also return a `downloadUrl`: a signed link that downloads
the PDF with no credential of its own, so an agent's shell can save it with
`curl -o document.pdf <downloadUrl>`. The link expires after 15 minutes;
`get_render_download_url` issues a fresh one for any artifact the caller owns
(artifacts are kept for 7 days). The PDF is still returned as an embedded
base64 resource for clients that render attachments.

| Tool | Wraps | Purpose |
| --- | --- | --- |
| `validate_dsl` | `/preview/validate` | Catalog + accessibility check, no render. |
| `validate_markdown` | `/md/validate` | Heading hierarchy + alt-text check for markdown. |
| `render_markdown` | `/md` | **Billed** render of markdown to PDF (1 credit / 10 pages). |
| `render_dsl_preview` | `/preview` | Free watermarked preview PDF (returned as base64 blob). |
| `render_template` | POST `/render` | **Billed.** Render a saved template to a real PDF (1 credit / 10 pages). A small makespdf.com link on each page on the Free and Hobbyist plans, unless the account holds Growth credits; clean otherwise. |
| `get_render_download_url` | GET `/artifacts/:id/pdf` | Free. Re-issue a short-lived signed download URL for an artifact the caller owns. |
| `save_template` | POST `/templates` | Persist a DSL template with a name. |
| `list_templates` | GET `/templates` | List the caller's templates. |
| `get_template` | GET `/templates/:id` | Fetch one template with full DSL. |
| `update_template` | PUT `/templates/:id` | Update DSL and/or name. |
| `delete_template` | DELETE `/templates/:id` | Remove a template. |
| `report_feedback` | — | Tell the makesPDF team where you got stuck or what could be better. Free; read by humans, no real-time reply. |

Plus two resources — `file:///skills/pdf-template-author.md`, the canonical
authoring skill, and `agent-tools://ownership`, a static JSON ownership-proof
document for the agent-tools directory. MCP clients that support resources fetch
them on demand.

## 1. Authentication: a key only if you need one

Only the API-key route needs one. VS Code, Cursor, Gemini CLI, Antigravity, opencode,
Claude Code, claude.ai and Claude Desktop can sign in by URL with no key at all —
the VS Code, Cursor, Gemini CLI, Antigravity and opencode configs are in the next step, and
the Claude clients are under
[add by URL](https://makespdf.com/docs/mcp#add-by-url) below. For clients that take a
static header (CI, scripts, clients without OAuth), create a key at
[Settings → API Keys](https://makespdf.com/settings/api-keys). You'll paste it into your
client's config below.

## 2. Register the server with your client

Every client uses the same endpoint; what varies is the config file, and the
stdio bridge a local Claude Desktop config needs. claude.ai, Claude Desktop
connectors, Claude Code, VS Code, Cursor, Gemini CLI, Antigravity and opencode can sign in
by URL, with no key at all — their configs are below. A static API key is the alternative for CI,
scripts and clients without OAuth. Restart the client after editing.

### Claude Desktop

Claude Desktop's `claude_desktop_config.json` only launches local stdio servers,
so it takes a `command` and its `args` — not a remote `url` with `headers`,
which Desktop ignores. Bridge to makesPDF with
[mcp-remote](https://github.com/geelen/mcp-remote). It needs Node.js 18 or later
— Desktop uses your system Node, so a newer version installed elsewhere does not
count — and `npx` has to be on the PATH Desktop inherits: a macOS Desktop
launched from the Dock does not get your shell's PATH, so `npx: not found` is
the usual first failure. When the server doesn't appear, Desktop logs the bridge
to `~/Library/Logs/Claude/mcp*.log` (macOS) or
`%LOCALAPPDATA%\Claude\Logs\mcp.log` (Windows), and adding `--debug` to the
`args` logs more.

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`.
Windows: `%APPDATA%\Claude\claude_desktop_config.json`.

```json
{
  "mcpServers": {
    "makespdf": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://makespdf.com/api/v1/mcp",
        "--header",
        "Authorization:${MAKESPDF_AUTH}"
      ],
      "env": {
        "MAKESPDF_AUTH": "Bearer mpdf_your_api_key"
      }
    }
  }
}
```

The header value names an environment variable that carries the key, instead of
embedding the key itself, with no space after the colon: Desktop on Windows
mangles a `--header` argument that contains spaces before `npx` sees it, while a
space inside an environment value is safe. `mcp-remote` substitutes
`${MAKESPDF_AUTH}` from its own environment, which is what the `env` block
provides; when the variable is absent it logs a warning and sends the literal
placeholder, which the server rejects. Never put the key in `args` directly —
process arguments are readable from the process list — and if you'd rather keep
it out of the config file too, `mcp-remote` also takes `--header-file`, a file of
`Name: value` lines read literally.

A rejected key does not surface as "invalid API key" through the bridge: makesPDF
answers `401` to any POST carrying a bad token — including the `initialize` that
opens the session — so the connection fails before any tool runs and the MCP
client library reports `Error POSTing to endpoint` for the `401` (the log above
carries it). No sign-in prompt appears: `mcp-remote` only starts OAuth when a
`GET` of the server URL answers `401`, and this endpoint is POST-only for MCP
traffic (a `GET` that asks for `text/event-stream` gets `405`; a browser
`GET` gets a setup page). If that happens, check that `MAKESPDF_AUTH` holds a real key and not
the placeholder above.

> **Custom connector:** to add makesPDF by URL instead (*Settings → Connectors →
> Add custom connector* with `https://makespdf.com/api/v1/mcp` as the URL), leave **Request
> headers** empty and sign in with OAuth — see
> [add by URL](https://makespdf.com/docs/mcp#add-by-url) below.
> Putting an API key under Request headers instead uses Claude's static-headers
> beta, which is open to a limited set of organizations.

### Claude Code

Add to your user or project `.mcp.json` (or use `claude mcp add`):

```bash
claude mcp add --transport http makespdf \
  https://makespdf.com/api/v1/mcp \
  --header "Authorization: Bearer mpdf_your_api_key"
```

### Cursor

Global config at `~/.cursor/mcp.json`, or per-project at `.cursor/mcp.json`.
Cursor signs in by URL when the entry names its own client document as the
client ID:

```json
{
  "mcpServers": {
    "makespdf": {
      "url": "https://makespdf.com/api/v1/mcp",
      "auth": {
        "CLIENT_ID": "https://cursor.com/oauth/mcp-client.json"
      }
    }
  }
}
```

Cursor then shows its **Authenticate** prompt on first use; the consent page
names cursor.com and the localhost return address, and the tools work with no
API key.

**Alternative — API key.** If you would rather not use OAuth (CI, or a Cursor
build without the auth field), add the Bearer header instead:

```json
{
  "mcpServers": {
    "makespdf": {
      "url": "https://makespdf.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer mpdf_your_api_key"
      }
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`, or to the `mcp.servers` block in your user
settings. VS Code 1.106 and later sign in by URL with no key:

```json
{
  "servers": {
    "makespdf": {
      "type": "http",
      "url": "https://makespdf.com/api/v1/mcp"
    }
  }
}
```

On first use VS Code opens the makesPDF consent page using its client ID
metadata document, and keeps the sign-in across chats.

**Alternative — API key.** For older VS Code builds, CI or scripts:

```json
{
  "servers": {
    "makespdf": {
      "type": "http",
      "url": "https://makespdf.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer mpdf_your_api_key"
      }
    }
  }
}
```

### Gemini CLI

Install the makesPDF extension. It carries the server URL and the sign-in
settings, so there is nothing to configure:

```bash
gemini extensions install https://github.com/makesPDF/makespdf-mcp
```

Then run `/mcp auth makespdf` once in a Gemini CLI session. It opens the
makesPDF consent page in your browser, and Gemini CLI keeps the sign-in for
later sessions.

### Antigravity

Install the makesPDF plugin. Antigravity signs in with its own client ID
metadata document, so there is nothing to configure:

```bash
agy plugin install https://github.com/makesPDF/makespdf-mcp
```

Antigravity opens the makesPDF consent page in your browser when the server
first connects. To sign in yourself, open `/plugin`, expand makespdf under
Installed, and choose **Sign in**. To add makesPDF without the plugin, put
`{ "serverUrl": "https://makespdf.com/api/v1/mcp" }` under `mcpServers` in
`~/.gemini/config/mcp_config.json` (the Antigravity IDE needs version 2.6.0 or later
for this).

### opencode

Add the server under `mcp` in `opencode.json` (per project) or
`~/.config/opencode/opencode.json` (everywhere). No key and no headers:
opencode signs in with its own client ID metadata document.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "makespdf": {
      "type": "remote",
      "url": "https://makespdf.com/api/v1/mcp"
    }
  }
}
```

Then run `opencode mcp auth makespdf` once. It opens the makesPDF consent page
in your browser, and opencode keeps the sign-in for later sessions.

### Other clients

Any client that supports the MCP Streamable HTTP transport (2025-03-26 revision
or later) will work. Point it at `https://makespdf.com/api/v1/mcp`. Clients with OAuth
support sign in by URL; anything else sends
`Authorization: Bearer <key>` on every POST that calls a tool. Clients and
registries that configure themselves can read the MCP Server Card at
`https://makespdf.com/api/v1/mcp/server-card`, also listed from `/.well-known/mcp.json`
and `/.well-known/ai-catalog.json`.

## Or: add by URL in claude.ai / Desktop (sign in, no key)

claude.ai, Claude Desktop's connector directory and mobile can add a remote
server by URL and sign in with OAuth. That route needs no API key and no
Request-headers beta, and it is what to use when a non-developer wants makesPDF
in Claude. Cursor and VS Code sign in by URL too — their configs are in step 2
above. The server advertises its authorization server at
`/.well-known/oauth-protected-resource/api/v1/mcp`, and the first tool call
starts the sign-in.

1. In claude.ai: **Customize → Connectors → Add custom connector**. In Claude
   Desktop, use the same **Connectors** screen — not
   `claude_desktop_config.json`, which only launches local stdio servers.
2. Set the URL to `https://makespdf.com/api/v1/mcp`. Leave the client ID,
   client secret and Request headers fields empty.
3. Ask Claude for a makesPDF action (for example "validate this template"). The
   tool call returns a sign-in challenge, Claude opens the makesPDF consent
   page, and you approve the request. The page names the requesting client by
   the host of its `client_id` URL and shows where your browser will return; it
   never trusts a client-supplied display name.
4. Afterwards the connector stays live while you use it: access tokens are
   short-lived and refresh automatically, and a connection unused for 30 days
   lapses. There is no connected-apps list yet; removing the connector in
   Claude stops it using makesPDF, and the tokens expire within 30 days of
   their last use. Each token is bound to makesPDF's MCP URL and accepted on
   `/api/v1/mcp` only — never on the REST render endpoints.

**Claude Code** can use the same sign-in instead of a header:

```bash
claude mcp add --transport http makespdf https://makespdf.com/api/v1/mcp
# then, inside Claude Code:
/mcp   # choose makespdf -> Authenticate -> approve in the browser
```

Use an API key instead when the client cannot do OAuth, when you are scripting
the REST API, or when the connector must run unattended with no one to approve a
consent prompt. The two credentials can coexist: an API-key request behaves
exactly as it did before OAuth existed.

## 3. Verify the connection

Most clients list connected MCP servers in a status panel. Quick sanity check
from the command line:

```bash
curl -X POST https://makespdf.com/api/v1/mcp \
  -H "Authorization: Bearer mpdf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

You should see a JSON response listing all twelve tools. A `401` means the API
key isn't valid; a `200` with an empty tool array shouldn't happen — if it does,
file an issue.

Discovery works without a key. `initialize`, `tools/list`, `resources/list` and
`resources/read` answer on an unauthenticated POST, so a client can show you the
tool surface before you sign up. `tools/call` is the method that needs the Bearer
token. Note that an *invalid* key still returns `401` on every method — drop the
header entirely to hit the anonymous path.

## 4. Try it

Ask your AI something like:

```text
Create an invoice template for Acme Corp with 3 line items, save it, and
show me the preview PDF.
```

The agent should:

1. Read the `pdf-template-author.md` resource (prompted by the server's
   instructions).
2. Draft DSL and call `validate_dsl`.
3. Fix any reported issues and call `render_dsl_preview`.
4. Call `save_template` once you confirm the result.
5. (Optional, billed) Call `render_template` with the new ID and real data to
   produce the deliverable PDF, then download its `downloadUrl` to save it.

## Limits and cost

- **Rate limits** are shared with the REST endpoints each tool wraps — MCP calls
  and curl/CLI calls draw from the same per-endpoint bucket (e.g. 200/hour for
  `preview`, 500/hour for the validate tools, 100/hour for template writes).
- **Billing:** every authoring tool is free. The one billed tool is
  `render_template`, which deducts 1 credit per 10 pages on success — same rate
  as `/api/v1/render`. The tool description and the JSON metadata it returns
  (`creditsDeducted`, `creditsRemaining`) make the cost explicit so a chat session
  can surface it to the human. `render_markdown` bills identically and returns the
  same metadata.
- **Watermarks:** `render_dsl_preview` always bakes a "PREVIEW — NOT FOR USE"
  overlay into the PDF and is free. `render_template` follows the caller's plan:
  free-plan output is stamped, paid plans render clean.

## What’s next

- [Integrate into your app](https://makespdf.com/docs/integrate) — three copy-paste recipes
  (backend render, hosted MCP, Vercel AI SDK tools) for drop-in AI-built PDF
  templates.
- [Bring your own AI](https://makespdf.com/docs/ai-setup) — skill-only flows and CLI-based
  authoring.
- [API Reference](https://makespdf.com/docs/api) — the REST endpoints each MCP tool wraps.
- [pdf-template-author.md](https://makespdf.com/skills/pdf-template-author.md) — the
  canonical authoring skill, also available as an MCP resource.
