For AI agents: a documentation index is available at /llms.txt — every docs page also has a markdown twin (append .md to the page URL).

MCP server

makesPDF exposes its authoring loop as a Model Context Protocol 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 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.

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.

ToolWrapsPurpose
validate_dsl/preview/validateCatalog + accessibility check, no render.
validate_markdown/md/validateHeading hierarchy + alt-text check for markdown.
render_markdown/mdBilled render of markdown to PDF (1 credit / 10 pages).
render_dsl_preview/previewFree watermarked preview PDF (returned as base64 blob).
render_templatePOST /renderBilled. 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_urlGET /artifacts/:id/pdfFree. Re-issue a short-lived signed download URL for an artifact the caller owns.
save_templatePOST /templatesPersist a DSL template with a name.
list_templatesGET /templatesList the caller’s templates.
get_templateGET /templates/:idFetch one template with full DSL.
update_templatePUT /templates/:idUpdate DSL and/or name.
delete_templateDELETE /templates/:idRemove 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 below. For clients that take a static header (CI, scripts, clients without OAuth), create a key at 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. 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 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:

text
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:

text
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