Using BrewMyPDF from an AI agent (MCP)

BrewMyPDF speaks the Model Context Protocol, so an agent can find your templates, learn what data each one needs, and render a PDF — with your API key, your quota and your audit trail.

What this is

BrewMyPDF is an MCP server, so an AI agent can list your templates and render one without you writing any glue code. It is the same account, the same API key, the same quota and the same audit trail as the REST API — the agent is not a separate identity.

The server is stateless: one HTTP POST carries one JSON-RPC 2.0 message. There is no session to open and nothing to keep alive, so a dropped connection costs you nothing.

Connecting

Point any MCP client at https://brewmypdf.com/mcp and send your API key in the Authorization header as a bearer token. Note that this header is different from the REST API, which uses x-api-key — the key itself is the same one, issued in the console under API keys.

mcp.json

{
  "mcpServers": {
    "brewmypdf": {
      "url": "https://brewmypdf.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

A wrong or missing key answers unauthorized and nothing else. We do not send a WWW-Authenticate challenge, because advertising a discovery flow we do not run would send your client down a path that dead-ends. If you get unauthorized, check the header name first.

tools/list

curl -X POST https://brewmypdf.com/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "content-type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

API keys start on the Professional plan, so plans below it cannot connect an agent.

The four tools

Every tool works on a template you already saved. None of them create or edit templates — see the limits below.

`list_templates`	List the PDF templates on this account. Returns id, name and last-updated time. Call this first — every other tool needs a template_id from here.
`describe_template_schema`	Describe the JSON data a template expects. Returns a JSON Schema plus the flat list of binding paths found in the template. Types are intentionally left open — the template only says which values it uses, not what they must be. Call this before preview_template or render_pdf.
`preview_template`	Render a template with data to HTML, without producing a PDF. Free and fast — use it to check your data fits before calling render_pdf. Returns the HTML and any binding warnings (a warning is not a failure: it tells you which value was missing or wrong).
`render_pdf`	Render a template with data to a PDF and return a download URL. This consumes one render from the account quota, so preview_template first. If the render takes longer than the wait window you get a job_id with status "queued" instead of a URL.

The order to call them

list_templates gives you ids. describe_template_schema turns an id into the exact JSON shape that template expects, including every binding path — call it before you send data instead of guessing field names. preview_template renders HTML for free so you can check the data fits. render_pdf then spends one render and returns a signed download URL.

If a render takes longer than the wait window you get a job id with status queued instead of a URL. That is not a failure — the job is running, and the same job id works against the REST API.

The server also sends this order to the model itself, in the instructions field of the initialize response. Clients may put that text in the system prompt, so a well-behaved agent knows the sequence before it calls anything.

What it cannot do

It cannot create or edit a template. Templates are made in the web editor or through the REST API (POST /v1/templates and PUT /v1/templates/{id}). If an agent has no template to work with, a person has to make one first.

It renders PDF only. For PNG or JPEG, and for webhooks, batches, PDF operations and everything else, use the REST API.

The tools do not call a language model. Generating a template from a description is a separate feature in the console and is metered in credits.

Two kinds of failure

A tool that ran and failed answers with isError and a message — a missing template, a bad value, a quota that ran out. Read it, fix the input and try again.

A JSON-RPC error means the call never started: an unknown tool name, or a required argument you left out. Retrying with different values will not help; re-read the tool list instead.