Skip to content

PdfBroker.io MCP Server

PdfBroker.io provides a remote MCP (Model Context Protocol) server that lets AI agents generate PDF documents directly from conversation. Configure it once, and your assistant can produce invoices, reports, certificates and compliance documents — it writes the HTML, calls the PdfBroker.io rendering engine, and returns a download link.

The server is hosted, not installed. It runs as a remote Streamable HTTP service, so it works from cloud-hosted agents and server-side workflows that have no local filesystem to write to.

Official MCP Registry

The server is published in the official MCP Registry under a DNS-verified namespace:

io.pdfbroker/pdf

DNS verification means the registry has confirmed the entry was published by the owner of pdfbroker.io. If you find a PdfBroker MCP server under any other namespace, it is not ours.

Clients and directories that read the registry can discover and install the server from that name without hand-editing configuration. If your client offers a registry browser, look there first — the manual configurations below are the fallback. 

curl "https://registry.modelcontextprotocol.io/v0.1/servers/io.pdfbroker%2Fpdf/versions/latest"

Available tools

Once connected, your agent has access to five tools:

Tool Description Plan
html_to_pdf HTML and CSS to PDF using WeasyPrint. Full CSS Paged Media support, PDF/A and PDF/UA conformance. Starter and above
html_to_pdf_wk HTML to PDF using wkhtmltopdf. Executes JavaScript before rendering. Free tier
merge_pdfs Combine multiple PDF documents into a single file. Free tier
pdf_to_image Render PDF pages as PNG or JPEG images. Free tier
write_text_on_pdf Overlay text on an existing PDF document. Free tier

See the WeasyPrint service documentation for the full set of rendering arguments, and PDF Services for the underlying utility endpoints.

Why the server returns download URLs

Tool responses contain a time-limited download URL, not the PDF itself. This is deliberate.

Returning a PDF as base64 inside a tool result can consume tens of thousands of tokens of the agent's context window for a single document — and the agent gains nothing from those bytes, because it cannot read them. A URL costs a few dozen tokens instead, and it is a link you can hand to a user or paste into an email rather than a file path on whichever machine happened to run the server.

Download URLs expire after 30 minutes. Document content is deleted once the PDF has been generated and the download window has closed.

Prerequisites

Credentials are sent per request and are never stored by the MCP server. See Authentication for how PdfBroker.io credentials work in general.

Claude Code

Claude Code supports custom HTTP headers on remote MCP servers, so it connects directly to https://mcp.pdfbroker.io/ with no wrapper. 

claude mcp add-json pdfbroker '{
  "type": "http",
  "url": "https://mcp.pdfbroker.io/",
  "headers": {
    "X-PdfBroker-ClientId": "YOUR_CLIENT_ID",
    "X-PdfBroker-ClientSecret": "YOUR_CLIENT_SECRET"
  }
}'

Run /mcp inside a session to confirm pdfbroker appears with its tools.

Claude Desktop

Claude Desktop cannot set custom HTTP headers on remote MCP connections, so it uses the @pdfbroker/mcp-server npm wrapper over stdio. Open Settings → Developer → Edit Config and add: 

{
  "mcpServers": {
    "pdfbroker": {
      "command": "npx",
      "args": ["-y", "@pdfbroker/mcp-server"],
      "env": {
        "PDFBROKER_CLIENT_ID": "YOUR_CLIENT_ID",
        "PDFBROKER_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Restart Claude Desktop completely, then check the tools icon at the bottom of the chat window to verify the PdfBroker tools are listed.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "pdfbroker": {
      "command": "npx",
      "args": ["-y", "@pdfbroker/mcp-server"],
      "env": {
        "PDFBROKER_CLIENT_ID": "YOUR_CLIENT_ID",
        "PDFBROKER_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Restart Cursor to load the configuration.

VS Code

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "pdfbroker": {
      "command": "npx",
      "args": ["-y", "@pdfbroker/mcp-server"],
      "env": {
        "PDFBROKER_CLIENT_ID": "YOUR_CLIENT_ID",
        "PDFBROKER_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Open Copilot chat in Agent mode and use the Select Tools icon to verify the PdfBroker tools are available.

Your first PDF

Once connected, try a prompt like this:

Create a one-page PDF with a heading “Project Status Report”, today's date, and a summary table with three columns: Task, Status, and Owner. Use the html_to_pdf tool with A4 paper size.

The agent generates the HTML and CSS, calls the tool, and returns a download link valid for 30 minutes.

Prompts that produce better output:

  • Be specific about layout. “A4 landscape with 2cm margins” beats “make a PDF”.
  • Name the conformance level when it matters. Say “use PdfUA1 conformance” for accessible documents, or “PdfA1b” for archival.
  • Iterate. Ask the agent to adjust colours, add page numbers, or embed a logo as a base64 image, then regenerate.

Choosing an engine

Consideration html_to_pdf (WeasyPrint) html_to_pdf_wk (wkhtmltopdf)
CSS Paged Media — headers, footers, page numbers Full support No
JavaScript execution No Yes
PDF/A and PDF/UA conformance Yes No
Rendering style Print-ready document layout Browser screen capture
Best for Invoices, contracts, reports, compliance documents JavaScript-rendered pages, quick snapshots

For most AI-generated documents, html_to_pdf is the right choice. Language models write semantic HTML and CSS naturally, which is exactly what WeasyPrint renders best. A fuller treatment is in WeasyPrint vs wkhtmltopdf.

Multi-page documents

WeasyPrint handles pagination through CSS Paged Media. Ask the agent for page furniture explicitly and it will produce CSS along these lines: 

@page {
  margin: 2cm;
  @top-left { content: "Acme Consulting AB"; font-size: 9pt; color: #666; }
  @bottom-right { content: "Page " counter(page) " of " counter(pages); font-size: 9pt; }
}
tr { page-break-inside: avoid; }

This is the capability html_to_pdf_wk does not have.

Calling the server programmatically

If you are embedding document generation in your own product rather than working from a chat client, connect to the MCP server directly.

C# with the MCP C# SDK

using ModelContextProtocol.Client;

var transport = new HttpClientTransport(new HttpClientTransportOptions
{
    Endpoint = new Uri("https://mcp.pdfbroker.io/"),
    Headers = new Dictionary<string, string>
    {
        ["X-PdfBroker-ClientId"] = configuration["PdfBroker:ClientId"]!,
        ["X-PdfBroker-ClientSecret"] = configuration["PdfBroker:ClientSecret"]!
    }
});

var mcpClient = await McpClient.CreateAsync(transport);

var result = await mcpClient.CallToolAsync("html_to_pdf", new Dictionary<string, object?>
{
    ["html"] = invoiceHtml,
    ["conformanceLevel"] = "PdfA1b",
    ["paperSize"] = "A4"
});

var downloadUrl = result.Content.OfType<TextContentBlock>().First().Text;

The SDK integrates with Microsoft.Extensions.AI, so the tool list can be passed straight to any IChatClient alongside a user prompt.

cURL

curl -X POST https://mcp.pdfbroker.io/ \
  -H "Content-Type: application/json" \
  -H "X-PdfBroker-ClientId: YOUR_CLIENT_ID" \
  -H "X-PdfBroker-ClientSecret: YOUR_CLIENT_SECRET" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "html_to_pdf",
      "arguments": {
        "html": "<html><body><h1>Test</h1></body></html>",
        "paperSize": "A4"
      }
    }
  }'

Credentials and multi-tenant use

Each user or tenant should have their own PdfBroker.io credentials, passed as X-PdfBroker-ClientId and X-PdfBroker-ClientSecret headers. The MCP server does not store credentials — it creates an authenticated client per request.

HTML content is sent to PdfBroker.io for rendering over HTTPS and deleted after generation. Rate limits apply per credential pair according to your subscription tier. Agents can issue requests quickly, so monitor usage if you are running production workloads.

Troubleshooting

Tools do not appear after setup
Confirm Node.js 18 or later is installed with node --version, and restart the client fully after editing configuration.
Authentication errors
Check the Client ID and Client Secret at Members → API Credentials and confirm the subscription is active.
“PDF generation failed”
WeasyPrint is strict about well-formed HTML. Unclosed tags and missing <html> or <body> wrappers are the usual causes.
html_to_pdf is unavailable
WeasyPrint requires a Starter plan or above. The free tier includes html_to_pdf_wk only. See pricing.

Further reading