Full agent reference

Let an AI agent design your PDFs

PDFEx speaks MCP — the open protocol that lets an agent use a service as a set of tools. Point Claude, Cursor, VS Code or any MCP host at https://pdfex.io/mcp and your agent can design a template, look at a picture of the result, fix what is wrong, save it, and print real PDFs from it. No SDK to install, no glue code, no curl.

It is the same API you already use by hand, and the same API key — just handed over in a shape an agent can drive by itself.

Connect in one minute

Create a key at API Keys (the same key your REST integration uses) and add this to your MCP host's config:

{
  "mcpServers": {
    "pdfex": {
      "type": "http",
      "url": "https://pdfex.io/mcp",
      "headers": { "Authorization": "Bearer pdfex_your_key_here" }
    }
  }
}

Most hosts let you read the key from an environment variable instead of pasting it — set the variable name PDFEX_API_KEY in your host's environment where it supports that. The header must be on the connection, not on individual tool calls.

What you are connecting to

The authoring loop

This is the workflow the server itself recommends (it ships as a prompt, see below). Nine tools, but only one habit matters: look before you save.

1. 1
   Read the contractget_capabilities

   The engines, the field types, the units, the page sizes, your plan limits. One call, so the agent never guesses a field shape or a page size.

2. 2
   Start from a working exampleget_samples

   Invoices, certificates and pay stubs, in both engines. Agents design far better by adapting a real template than by inventing JSON from a description.

3. 3
   Write the template

   pdfme coordinates in millimetres, or plain HTML and CSS with {{variables}} for the data.

4. 4
   Check it cheaplyvalidate_template

   Catches malformed markup and unsupported field types without rendering anything. Fast, and free of side effects.

5. 5
   Look at itpreview_template

   The important one. A real render through the production pipeline, returned as an image. This catches what validation cannot: a field hanging off the page, a font that will be substituted, data the sample never fills.

6. 6
   Fix and look again

   The agent sees the picture, adjusts, and previews once more. Repeat until the page looks right. Nothing has been saved yet.

7. 7
   Save itcreate_template

   Only now, when the preview looks correct. This is the first step that writes anything — and the first that counts against your plan's template limit.

8. 8
   Print real PDFs

   The saved template now works everywhere: the dashboard, the REST API, and anything else that can call POST /api/pdf/token.

The nine tools

Every tool is a thin wrapper over the same service your REST calls use. There is no second implementation to drift out of sync, and no second contract to learn — including the field names.

Why the read/write split is worth understanding

Each tool declares readOnlyHint, destructiveHint and idempotentHint to the host. A good MCP client uses them: six read tools can be auto-approved, delete_template can be made to ask first. That means you can hand an agent your keys without handing it the ability to quietly delete your work.

A resource and a prompt

Alongside the tools, the server publishes reading material and a ready-made workflow. Hosts surface these as “resources” and “prompts”.

Two engines, two philosophies

Every template is built with one of two engines. They produce the same kind of file from the same API — but you think in completely different units.

Which should you pick?

The pdfme engine, in detail

Everything in a pdfme template is measured in millimetres, with the origin at the top-left of the page. Font sizes are the one exception: those are in points, because that is how type is measured.

What the coordinates mean

This is a real A4 page — 210 × 297 mm — with the two fields from the example below drawn in place. Left and top are the position; width and height are the box the text may occupy.

Template structure

{
  "basePdf": { "width": 210, "height": 297, "padding": [20, 20, 20, 20] },
  "schemas": [
    [
      { "name": "title", "type": "text", "position": { "x": 20, "y": 20 },
        "width": 170, "height": 12, "fontSize": 24, "alignment": "center" },
      { "name": "body",  "type": "text", "position": { "x": 20, "y": 40 },
        "width": 170, "height": 60, "fontSize": 11 }
    ]
  ]
}

• schemas is an array of pages. Each page is an array of fields. One page here.
• Every field needs a unique name — that name is the variable your data fills — plus type, position, width and height.
• Omit basePdf and you get A4 portrait, no padding.
• Fields marked readOnly are treated as fixed decoration and are not counted as variables.

Field types

A table field, in full

{
  "name": "line_items",
  "type": "table",
  "position": { "x": 20, "y": 60 },
  "width": 170,
  "height": 80,
  "head": ["Description", "Qty", "Amount"],
  "headWidthPercentages": [60, 15, 25],
  "fontSize": 10
}

// the value is an array of arrays of strings — one inner array per row:
"line_items": [
  ["Consulting", "10", "$800.00"],
  ["Platform licence", "1", "$450.00"]
]

Older templates that store each page as an object keyed by field name instead of an array are still accepted — they are normalised automatically, so nothing you built before breaks.

The HTML engine, in detail

HTML templates are ordinary web pages with Handlebars placeholders. They are rendered by headless Chromium using its print-to-PDF pipeline — the same route your browser's “Save as PDF” takes.

How open it is

This is the part people underestimate. It is not a template markup language with a subset of CSS bolted on — it is a real browser engine. All of the following work:

• ✓Flexbox and CSS grid
• ✓Absolute and relative positioning
• ✓Linear and radial gradients
• ✓Borders, radius, box-shadow
• ✓Web-safe font stacks
• ✓Custom @font-face with base64
• ✓Tables that size to content
• ✓@page size and margins
• ✓page-break-before / after / inside
• ✓Repeating headers via thead
• ✓Generated content (:before, :after)
• ✓Counters and CSS counters
• ✓Multi-column text layout
• ✓writing-mode (vertical text)
• ✓Transforms and rotation
• ✓SVG inline in the markup

Data injection

<!-- a single value -->
<h1>Invoice {{invoice_number}}</h1>

<!-- a repeating block: one row per item in the array -->
<table>
  <thead><tr><th>Description</th><th>Amount</th></tr></thead>
  <tbody>
    {{#each items}}
    <tr><td>{{description}}</td><td>{{amount}}</td></tr>
    {{/each}}
  </tbody>
</table>

<!-- conditional content -->
{{#if is_paid}}<p class="paid">PAID</p>{{/if}}

Variables are extracted from your placeholders automatically — you never list them by hand. Nested data works the natural way: inside {{#each items}}, each field name is read from the current item, so one array builds a whole table.

The sandbox: what is deliberately switched off

Page size and pagination

PDFEx reads your CSS @page rule to work out the paper size. If there is no such rule it falls back to US Letter, and you can always override it explicitly with page_format.

@page { size: a4; margin: 12mm; }

{ "engine": "html", "page_format": "A3" }

Supported page sizes

CSS shorthand is understood too — size: letter, 8.5in 11in, and landscape all resolve to the right format. A certificate often just declares @page { size: landscape }.

Fonts and typography

Type is where documents are won or lost, so it is worth knowing exactly what each engine does.

body { font-family: Georgia, "Times New Roman", serif; }
code { font-family: ui-monospace, "SF Mono", Menlo, monospace; }

"fonts": [
  { "name": "Inter", "data": "AAEAAAATAQAABAAw…" }
]

Images

An image lives in the field's value, not in the schema — it is data you pass in, not something you place in the layout.

What is blocked

Loopback, link-local (including cloud metadata at 169.254.169.254), carrier-grade NAT, multicast and reserved addresses are refused before any request is made — as are localhost and the known metadata hostnames. Private ranges (10/8, 172.16/12, 192.168/16) and IPv6 ULA are intentionally allowed, so a self-hosted deployment can pull images from its own network.

The HTML engine fetches nothing

Only data: and about: requests are permitted; every other one is aborted. A <meta http-equiv="refresh"> or <iframe src> is refused too, because those reach the network without any JavaScript. Inline your images as data: URIs.

Ask what you are allowed to write

get_capabilities is the contract for your account, generated from the same list the validator enforces — so it can never advertise a field type that would then be rejected. Here is a real response:

{
  "engines": ["pdfme", "html"],
  "units": "millimetres, origin top-left of the page",
  "field_types": {
    "text": {
      "properties": ["fontSize", "alignment", "verticalAlignment", "fontColor",
                     "backgroundColor", "lineHeight", "characterSpacing"],
      "required": ["name", "type", "position", "width", "height"]
    },
    "image": { "value_format": "data:image/...;base64,... or http(s) URL fetched server-side" },
    "svg": {}, "line": {}, "rectangle": {}, "ellipse": {},
    "table": { "notes": "value is an array of string arrays; head defines the column
                count; headWidthPercentages must have one entry per head column" }
  },
  "page_formats": {
    "Letter": { "width_mm": 215.9, "height_mm": 279.4 },
    "Legal":  { "width_mm": 215.9, "height_mm": 355.6 },
    "A4":     { "width_mm": 210,   "height_mm": 297   },
    "A3":     { "width_mm": 297,   "height_mm": 420   },
    "A5":     { "width_mm": 148,   "height_mm": 210   }
  },
  "default_page": { "width_mm": 210, "height_mm": 297 },
  "fonts": ["Roboto"],
  "fonts_note": "per-template fonts arrays are accepted on create and preview;
                 this is the default fallback font",
  "template_limit": { "tier": "pro", "max_templates": 15, "used": 3 },
  "limits": {
    "preview_max_body_bytes": 10485760,
    "preview_max_pages": 10,
    "preview_max_scale": 4
  }
}

Note template_limit: it is your tier and your current usage, so an agent can tell whether it has room to save another template before trying and failing. Nothing here is guesswork.

Start from a working example

Three document types, each available in both engines. Fetching one gives you the complete template and its sample data, ready to adapt — which is a far better starting point than a blank schema.

Call get_samples with no arguments for the catalogue. Pass both kind and engine to get one in full — one without the other returns a helpful error rather than guessing at what you meant.

Limits and guardrails

These are the ceilings that keep a runaway agent from costing you anything. The numbers are published by get_capabilities too, so an agent can size its work correctly instead of discovering them by failing.

Preview images default to 1.5× — crisp enough for a model to read, small enough not to flood its context. Ask for more pages with pages and more detail with scale when you need them, but start small.page_count tells you whether content spilled onto a second page.

A worked example, start to finish

This is the loop above, executed for real. An invoice template, checked, rendered, and saved.

1 — Validate before spending a render

validate_template({
  engine: "html",
  html_template: "<html><body><h1>Invoice {{invoice_number}}</h1>" +
                 "<p>Billed to: {{customer_name}}</p>" +
                 "<table>{{#each items}}<tr><td>{{description}}</td>" +
                 "<td>{{amount}}</td></tr>{{/each}}</table></body></html>"
})

An invalid template is a successful answer, not an error — you get valid: false with the reasons:

{
  "valid": false,
  "engine": "html",
  "errors": ["html_template failed to compile: Parse error on line 1: …"]
}

2 — Preview, and actually look at the page

preview_template({
  engine: "html",
  html_template: "<html><body><h1>Invoice {{invoice_number}}</h1>…",
  sample_data: {              // ← note: preview uses sampleData, see the trap above
    "invoice_number": "INV-2024-001",
    "customer_name": "Acme Corp",
    "items": [ { "description": "Consulting", "amount": "$800.00" } ]
  },
  pages: 1,
  scale: 2
})

The result is a text summary, the page image, and — only if you ask with include_pdf: true — the PDF itself as a resource block:

3 — Save it

create_template({
  name: "Acme Invoice",
  engine: "html",
  html_template: "<html>…",
  sample_data: { "invoice_number": "INV-2024-001" }   // ← pdfme_schema / sample_data here
})

You get back the template id and its version. Keep both — you need the id to print, and the version to edit safely.

From a template to a live PDF

MCP is for authoring. Printing the finished document is a REST call, and it is deliberately simple: one call to request, one to fetch.

POST /api/pdf/token
{
  "template_id": "651…",
  "data": { "invoice_number": "INV-2024-001",
            "customer_name": "Acme Corp" }
}

{ "success": true,
  "token": "65eb…",
  "url": "/api/pdf/65eb…" }

Things that will bite you here

• The URL is the credential. GET /api/pdf/:token needs no API key — anyone holding the link can fetch the document. Treat it like a signed URL: don't log it, don't put it in a page your users can inspect, and don't email it around.
• Fetch it promptly. The 15 minutes run from when the token was created, not from when you first fetch it. After that you get a 410 and have to request a new one.
• It re-renders on each fetch. The PDF is not stored — it is generated on demand. Fetching twice can legitimately produce two slightly different files if the template changed in between.
• Same data, same look. Generation runs through exactly the pipeline your per-template preview used — same fonts, same page size, same pagination. If it looked right in the preview, it prints right.

Two agents, one template

If an agent might be editing a template that a human is also editing, tell it to guard its writes. Every template carries a version that goes up with each successful change. Read it, then send it back:

update_template({
  id: "651…",
  name: "Invoice v2",
  expected_version: 3
})

// → 200: the template is now version 4
// → conflict: nothing is written, and you are told the real version

{
  "error": "Version conflict — someone else changed this template since you read it.",
  "details": [
    "expected_version 3 does not match the current version 4; re-fetch the template and retry",
    "Re-read it with get_template, reapply your change, and pass the new version."
  ]
}

expected_version is optional, so an agent that prefers to just overwrite still can. But for anything you care about, use it — it turns a silent overwrite into a clear error you can recover from. Otherwise the loser of the race simply disappears.

Warnings: the things that render anyway

A preview can succeed and still be wrong — a field hanging off the page renders clipped, a missing font gets silently substituted. Rather than let that pass, every preview reports it:

When something goes wrong

Errors are written to be acted on, and they say what to do next. The usual suspects: