Generate PDFs from a Coding Agent with MCP

Preferred remote path: add https://api.relaypdf.com/mcp in Cursor or Claude and complete Clerk sign-in in the browser. Do not put a Bearer key in the host config unless the host cannot run OAuth. Local agents still run npx @relaypdf/cli setup, then npx @relaypdf/cli mcp. Call the pdf tool with html (or url, markdown, or a published templateId). Hosted tools return a 24-hour URL; stdio tools write out on disk. Never paste an API key into chat.

What MCP is here

This is the same public API as REST: POST /v1/pdf for HTML, URL, Markdown, or a published Handlebars template. Hosted MCP returns a 24-hour download URL, not file bytes. Stdio MCP writes bytes to disk, which is why every binary stdio tool requires out, a filesystem path the agent can read after the call.

Hosted MCP: Clerk login, not a pasted key

Remote Cursor, Claude Code, and similar hosts should use URL-only config. The host follows Protected Resource Metadata, opens Clerk, and stores the OAuth token. Bearer pdf_live_… headers still work for scripts that already have a key. Agents should never ask a human to paste an API key into chat.

claude mcp add --transport http relaypdf https://api.relaypdf.com/mcp

{ "mcpServers": { "relaypdf": { "url": "https://api.relaypdf.com/mcp" } } }

Stdio MCP: device flow on this machine

The local path is browser device login. login opens /cli/authorize. On approve, the CLI stores a key labeled CLI YYYY-MM-DD. setup logs in if needed and can write an env file at mode 0600.

whoami --json prints email and a masked key prefix. It never includes the secret. logout deletes the stored file. Revoke the key at Dashboard, API keys.

npx @relaypdf/cli login
npx @relaypdf/cli setup --env .env.local
npx @relaypdf/cli whoami --json

Do not put the API key in the MCP JSON if that file is shared or committed. Do not ask the model to echo credentials. Hosted MCP should use URL-only config plus Clerk login. RELAYPDF_API_KEY is for CLI, CI, and stdio when you already keep the secret in a store. setup once per machine or CI user is the intended local flow.

Local dashboard and API use RELAYPDF_APP_URL and RELAYPDF_BASE_URL, or --app / --api on login. Public defaults are https://relaypdf.com and https://api.relaypdf.com. login accepts --no-open if the browser cannot launch; you still complete /cli/authorize yourself.

Start the MCP server

After setup, start the stdio server. In a terminal this only confirms the process stays up. In an agent, the host owns the process.

npx @relaypdf/cli mcp

Cursor / Claude Desktop config, from the live CLI and MCP docs:

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

Recommended: run npx @relaypdf/cli setup first so the user approves browser auth before the host spawns mcp. The MCP process then uses stored credentials. Do not paste keys into prompts. See https://relaypdf.com/integrations/mcp and https://relaypdf.com/docs/mcp.

Call pdf for HTML

The tool name is pdf. It maps to POST /v1/pdf. Inputs are one of: html, url, markdown, or templateId plus templateData. On stdio, pass out as a filesystem path. On hosted MCP, the tool returns a 24-hour url instead of writing a local file.

async returns a job id instead of waiting for bytes.

From the same machine you can check the identical operation without MCP.

npx @relaypdf/cli pdf --html invoice.html --out invoice.pdf
npx @relaypdf/cli pdf --url https://example.com --out page.pdf
npx @relaypdf/cli pdf --markdown notes.md --out notes.pdf
npx @relaypdf/cli pdf --template invoice --data sample.json --out invoice.pdf

Tell the agent to write HTML to a file, then call pdf with that markup or path and a concrete out. After the tool returns, open the file.

Do not ask the model to invent a tool named convert_html_to_pdf, generate_pdf, or html2pdf. Those names belong to other MCP servers. RelayPDF tool is pdf.

url must be a public URL the API can fetch. markdown is first-class. A published template uses templateId or the CLI --template id or slug, plus JSON data.

Drafts from templates_create are not a substitute for publish. List drafts with templates_list. Stock layouts with templates_gallery.

Tools that exist (do not invent others)

The stdio server exposes the public surface, not a reduced demo set. Names below are the MCP tool names. Underscores where the CLI uses hyphens.

Tool	REST	Notes
pdf	POST /v1/pdf	html, url, markdown, or templateId plus templateData; out; async
image	POST /v1/images	html or url; fullPage; type
convert	POST /v1/convert	Office file path; to
merge	POST /v1/pdf/merge	PDF paths
extract	POST /v1/pdf/extract	pages
protect unlock	POST /v1/pdf/protect /unlock	password
raster from_images	POST /v1/pdf/raster /from-images	pages or image paths
stamp rotate delete_pages compress	POST /v1/pdf/*	watermark, degrees, pages
info text form_fields form_fill	POST /v1/pdf/info /text /form	inspect and fill
barcode	POST /v1/barcodes	type plus text or data
zip	POST /v1/zip	named files
templates_list gallery create publish	/v1/templates	Handlebars
jobs_get jobs_wait	GET /v1/jobs/:id	async
health	GET /health	liveness

CLI equivalents use hyphens: from-images, delete-pages, form-fields, form-fill, jobs get, jobs wait. MCP uses from_images, delete_pages, form_fields, form_fill, jobs_get, jobs_wait. health is GET /health.

Do not log HTML or file contents from the MCP process. That rule is in the CLI README.

Async, files, and cost

CLI --async returns a job id. --response url returns a 24-hour download. MCP pdf accepts async. Poll with jobs_get or wait with jobs_wait.

CLI form: jobs wait then an id and --out done.pdf. GET /v1/jobs/:id uses the same API key. File download URLs from the url response mode last 24 hours.

Wallet is prepaid in millicents (1 equals 0.001 USD). Documented launch prices: HTML PDF $0.0004/job + $0.0003/browser second; LibreOffice convert $0.0004/job + $0.0005/execution second; PDF tools $0.002.

Failed commands and HTTP 429 are not billed. Trial rate limit is 20 per minute. Funded is 60 per minute. Burst is 5 per 10 seconds. Failed jobs are not billed.

Same RelayPDFError codes as the Node SDK: unauthorized, payment_required, rate_limited, convert_unavailable, and the rest on the errors page.

Agent workflow that stays honest

The agent-use page is short. Run setup once per environment. Use CLI commands for deterministic scripts. Use mcp for tool-driven generation from agent runtimes.

Capture request IDs for audits and retries. That is the whole pattern at https://relaypdf.com/use-cases/agents.

A practical sequence: the human runs setup and Approve; host config points at npx -y @relaypdf/cli mcp; the agent may call health; the agent writes HTML and calls pdf with out; the agent reads or attaches the PDF.

For Office, convert with to set to pdf, or to docx, xlsx, html, or png as documented. For screenshots, image with html or url, optional fullPage and type.

If the host cannot spawn npx, install the CLI globally, then run relaypdf mcp and relaypdf --help.

Package version at research time was 0.1.4. Pin with npx @relaypdf/cli@0.1.4 if you need a lock. Requires Node.js 20+.

What this is not

This is not a local Chromium MCP. The render happens on RelayPDF. It is not a browser-driver stack or a community html2pdf server.

Those other servers have different tool names and no device-flow RelayPDF key. Do not mix their configs into the relaypdf entry.

Do not invent MCP resources, prompts, or sampling hooks that the docs do not list. Do not claim private-URL fetch, OCR, e-sign, PDF/A, or HIPAA.

url_not_allowed covers private, loopback, and metadata hosts on the public API. Do not send file:// as url.

Wire the host at https://relaypdf.com/integrations/mcp. Read the agent pattern at https://relaypdf.com/use-cases/agents.

Command and tool reference: https://relaypdf.com/docs/mcp and https://relaypdf.com/docs/cli.