HTML to PDF from a coding agent (MCP)

To do mcp html to pdf from a coding agent, install Node.js 20+, run npx @relaypdf/cli setup (device-flow login in the browser), then start the stdio server with npx @relaypdf/cli mcp. Point Cursor or Claude Desktop at that command. Call the pdf tool with html (or url, markdown, or a published templateId) and an out filesystem path. 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. Binary results are written to disk. Bytes are not returned over MCP. That is why every binary tool requires out, a filesystem path the agent can read after the call.

Auth: device flow, not a pasted key

Agents should never ask a human to paste an API key. The documented 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

RELAYPDF_API_KEY overrides the stored key when you already have a secret in a secret store. Do not print it. Do not put it in the MCP config JSON if the host file is shared or committed. Do not ask the model to echo credentials. setup once per machine or CI user is the intended 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. Pass out as a path.

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.015 USD; LibreOffice convert 0.04 USD; PDF tools 0.005 USD.

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.