DEV Community: Gerardo Barrera

How to Let an AI Agent Generate Real PDFs (with an MCP server)

Gerardo Barrera — Sat, 20 Jun 2026 04:37:27 +0000

AI agents are great at producing text. But the moment you need an actual document — an invoice, a report, a certificate — they fall apart. You get markdown you have to format yourself, or (with Code Interpreter) a rough PDF from a Python lib with generic fonts and tables that never quite look right. There's no clean way to hand an agent the job of "produce a polished PDF."

So I gave my agents one tool that does exactly that, over MCP (Model Context Protocol). The agent describes the document, and gets back a link to a finished, editable PDF. Here's how to wire it up in about 5 lines of config.

Disclosure: I work on PDFMakerAPI — but the pattern here (give an agent a single, well-scoped tool that returns a reviewable artifact) applies to any MCP server. The config below just happens to use mine.

30-second MCP refresher

MCP is the open standard for giving an AI agent tools. You point your client (Claude Desktop, Cursor, Windsurf, Cline, VS Code, ChatGPT…) at an MCP server, and the agent can now call whatever functions that server exposes. No glue code, no custom integration per client — that's the whole appeal.

The server we're adding exposes exactly one tool: create_document. (One tool on purpose — a small, predictable surface area is easier for an agent to use correctly than a grab-bag of twenty.)

Step 1 — Add the server

Drop this into your client's MCP config (Claude Desktop: Settings → Developer → Edit Config; Cursor: ~/.cursor/mcp.json; same idea elsewhere):

{
  "mcpServers": {
    "pdfmakerapi": {
      "command": "npx",
      "args": ["-y", "@pdfmakerapi/mcp"]
    }
  }
}

Restart the client. That's the entire setup — no API key, no account.

Using a web client like Claude.ai or ChatGPT that can't run npx? Add the hosted endpoint as a custom connector instead:

https://api.pdfmakerapi.com/mcp

Step 2 — Ask for a document

Now just ask the agent in plain English:

"Make a professional invoice for Acme Corp — 3 line items, net 30."

The agent calls create_document, and you get back a link like:

https://app.pdfmakerapi.com/d/019ee2fe-c503-71c0-aaf6-68cf33ca096c

Open it and you'll see the finished invoice — and you can edit any field before downloading the PDF. Here's a real one to click:
👉 Live invoice example

It works for invoices, receipts, certificates, reports, resumes, letters — if the agent can describe it, it can lay it out with headings, tables, and your data.

Why the "editable link" matters for agents

This is the part I actually care about, and it's why I didn't make the tool just spit out a final PDF.

If you've spent any time running agents in production, you know the failure mode isn't "bad answer" — it's a wrong action that's already done. An agent that emails the wrong customer or files the wrong number is worse than one that just says something dumb.

Returning an editable document instead of a finalized file builds a natural human-in-the-loop checkpoint into the workflow:

The agent drafts the document from the request.
A human opens the link, checks it, fixes anything, and downloads.

So the agent does the tedious 90% (layout, structure, pulling the data together), but a person stays in control of what actually ships. For anything that leaves the building — an invoice to a client, a certificate with someone's name on it — that checkpoint is worth a lot more than full autonomy.

What it does not do (so you scope it right)

Being straight about the edges:

It generates documents — it does not read or edit a PDF you upload. Different problem.
It returns an editable web document + a downloadable PDF, not a blank fillable form to hand out.

If your agent needs to produce structured documents from data or a prompt, this fits. If it needs to parse existing PDFs, you want a different tool.

Under the hood (for the curious)

create_document takes a document model — a small JSON tree of nodes (text, containers, tables) with optional {{variables}} — and stores it, returning the share link. The agent can build that structure from a prompt, or you can POST it yourself to the same REST API if you'd rather skip the agent entirely. It's open source (MIT) if you want to read the tool definition: github.com/GerardoBarrera/pdfmakerapi-mcp.

Wrap-up

Giving an agent the ability to produce a real, reviewable document turned out to be a small change with a big payoff:

Add one MCP server (~5 lines).
Ask for the document in plain English.
Get an editable link a human can sign off on before it ships.

No markdown-to-PDF wrangling, no headless browser, and a built-in review step instead of blind autonomy.

If you're building agents that produce deliverables (not just text): do you let the agent finalize, or always hand off to a human to review first? Genuinely curious how others are drawing that line — drop it in the comments.

How to Generate a PDF from JSON in Node.js (without a headless browser)

Gerardo Barrera — Sat, 20 Jun 2026 04:29:56 +0000

If you've ever had to generate PDFs from a Node app — invoices, receipts, reports, certificates — you've probably reached for
Puppeteer or some headless-Chrome setup. It works… until you have to run it in production. Now you're shipping a 300MB Chromium
binary, babysitting a browser process, fighting memory leaks, and your "render a PDF" endpoint times out under load.

There's a simpler way: describe the document as JSON, POST it to an API, get a PDF back. No browser. In this post I'll show how
to go from a JSON payload to a finished, editable PDF in about 15 lines of Node.

Full disclosure: I built PDFMakerAPI, the tool I'm using here. There's a free tier, no API key needed to
try it, and the code below runs as-is.

## The idea: separate the data from the design

The trick to sane PDF generation is to stop gluing strings of HTML together. Instead you keep two things separate:

The design — a layout of text, tables, and containers (you can design this visually, or describe it as JSON).
The data — the actual values that change per document.

You merge them with one request and get back a link to the finished PDF. Let's do it.

## Step 1 — Describe the document as JSON

A document is just a tree of nodes. Here's a minimal one — a short welcome letter with a {{customer_name}} placeholder:

  const document = {
    name: "Welcome Letter",
    pageSize: "letter",
    variables: [
      {
        id: "var_name",
        name: "customer_name",
        type: "text",
        label: "Customer Name",
        defaultValue: "Alex Morgan",
      },
    ],
    children: [
      {
        id: "title",
        name: "Title",
        type: "text",
        order: 1,
        width: "full",
        content: "Welcome aboard 🎉",
        fontSize: "xl",
        fontWeight: "bold",
        style: { textColor: "#111827" },
      },
      {
        id: "body",
        name: "Body",
        type: "text",
        order: 2,
        width: "full",
        content:
          "Hi {{customer_name}}, thanks for joining. This whole PDF was generated from JSON in a single API call — no headless browser
  involved.",
        fontSize: "md",
        style: { textColor: "#374151" },
      },
    ],
  };

Anything in {{double_braces}} is a variable, so you can reuse the same layout with different data. The full schema (containers,
tables, images, fonts, page settings) is in the docs and repo — but the shape
above is all you need to start.

## Step 2 — POST it and get a link back

  const res = await fetch("https://api.pdfmakerapi.com/api/v1/documents", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ document }),
  });

  const { id, url } = await res.json();
  console.log(url);
  // → https://app.pdfmakerapi.com/d/<id>

That's it. The response is { id, url }, where url opens the finished document.

Prefer curl?

  curl -X POST https://api.pdfmakerapi.com/api/v1/documents \
    -H "Content-Type: application/json" \
    -d '{ "document": { "name": "Welcome Letter", "pageSize": "letter", "children": [ { "id": "t", "type": "text", "order": 1, "width":
  "full", "content": "Generated from JSON ✅", "fontSize": "xl", "fontWeight": "bold" } ] } }'

## Step 3 — The part Puppeteer can't do: an editable result

Here's the difference that matters. The link you get back isn't a flat, one-shot render — it opens an editable document. You (or
anyone you send the link to) can change any field in the browser and the preview updates live, then download the PDF.

Here's a real one generated this way — open it and edit a field:
👉 Live invoice example

That turns out to be a big deal in practice: your app drafts the document, but a human can review and fix it before it goes out —
instead of trusting whatever got rendered.

## Bonus: you don't even have to write the JSON

If hand-building the node tree feels tedious, you can skip it entirely. PDFMakerAPI ships an MCP server, so an AI agent (Claude,
Cursor, ChatGPT, etc.) can generate the document structure from a plain-English prompt:

  {
    "mcpServers": {
      "pdfmakerapi": { "command": "npx", "args": ["-y", "@pdfmakerapi/mcp"] }
    }
  }

Then just ask: "make an invoice for Acme with 3 line items" and it returns the same kind of editable link. Same engine, no JSON by
hand.

## When you should NOT use this

Being honest: an API isn't always the right call.

If you need to screenshot an existing web page to PDF, a headless browser is the right tool — that's literally what it's for.
If you're generating one PDF, once, locally, a library like pdfkit is fine.

Where this approach wins is generating structured documents from data, repeatedly, in production — invoices, receipts, reports,
certificates — without running a browser farm.

## Wrap-up

To generate a PDF from JSON in Node:

Describe the document (or let an AI agent describe it).
POST it to /api/v1/documents.
Get back a link to an editable, downloadable PDF.

No Chromium, no rendering servers, no timeouts. If you want to try it, the free tier gives you 100 PDFs/month with no card, and the MCP server is open source (MIT) on GitHub.

If you're generating PDFs in production today — what are you using, and what's been the most painful part? Curious to hear in the
comments.