Skip to content
PDFDispatch
Log in Sign up

Make PDFs from Claude Code, Cursor and VS Code with MCP

If you work with an AI assistant in your editor, you can ask it for a PDF the same way you ask it for code: "make an invoice from this JSON", "turn the contract in docs/ into a PDF". The assistant needs a tool for that. The PDFDispatch MCP server gives it one, hosted at https://mcp.pdfdispatch.com/mcp, with nothing to install. The assistant writes the HTML, the server turns it into a PDF with your PDFDispatch key, and the assistant downloads the result into your project.

This guide sets it up in Claude Code, Cursor and VS Code, then goes through four things you can ask for.

What you need

  • A PDFDispatch key from pdfdispatch.com/app/keys. Make a separate one for the assistant (call it "Claude Code" or "Cursor"), so you can revoke it alone.
  • The key in an environment variable, not in a file that goes into git:
export PDD_KEY=pdd_your_key_here

Put that line in your shell profile (~/.bashrc, ~/.zshrc) so your editor sees it too.

Add the server

Claude Code

One command:

claude mcp add --transport http pdfdispatch https://mcp.pdfdispatch.com/mcp \
  --header "Authorization: Bearer $PDD_KEY"

The shell fills in your key, and Claude Code stores it in ~/.claude.json, outside the project. The server is then available to you in the current project; add --scope user to have it in every project. Start Claude Code and type /mcp: pdfdispatch should be listed as connected.

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in one project). Cursor reads the key from your environment:

{
    "mcpServers": {
        "pdfdispatch": {
            "url": "https://mcp.pdfdispatch.com/mcp",
            "headers": {
                "Authorization": "Bearer ${env:PDD_KEY}"
            }
        }
    }
}

VS Code

Add .vscode/mcp.json. VS Code asks for the key the first time and keeps it in its secret storage, so the file can be committed:

{
    "inputs": [
        {
            "type": "promptString",
            "id": "pdfdispatch-key",
            "description": "PDFDispatch API key",
            "password": true
        }
    ],
    "servers": {
        "pdfdispatch": {
            "type": "http",
            "url": "https://mcp.pdfdispatch.com/mcp",
            "headers": {
                "Authorization": "Bearer ${input:pdfdispatch-key}"
            }
        }
    }
}

Other clients work if they can send a header to a remote MCP server: give them the URL and Authorization: Bearer pdd_.... Claude Desktop needs the mcp-remote bridge, and custom connectors in claude.ai cannot be used yet, because the server does not support OAuth sign-in. The MCP reference has the details.

How the assistant gets the PDF

The server has seven tools: html_to_pdf, markdown_to_pdf, url_to_pdf, office_to_pdf, merge_pdfs, screenshot and upload_file. The assistant picks one from your request. Each tool that makes a file answers with a download link like this:

https://mcp.pdfdispatch.com/files/3f9c.../invoice-1042.pdf

The link works for one hour and then stops, and the server tells the assistant to download what it wants to keep. Say where the file should go ("save it to out/invoice-1042.pdf") and it runs curl:

curl -fsSL -o out/invoice-1042.pdf "https://mcp.pdfdispatch.com/files/3f9c.../invoice-1042.pdf"

Two defaults differ from the API: paper is A4, and background colours and images are printed. Ask for Letter or landscape and the assistant passes it on.

Example 1: an invoice from data in your repo

Say your project has fixtures/order-1042.json with a customer, a few line items and a due date. Ask:

Make a PDF invoice for the order in fixtures/order-1042.json. Our company details are in
config/company.php. A4, a clean layout, the total in bold. Save it as out/invoice-1042.pdf.

The assistant reads both files, writes a complete HTML page with the CSS in a <style> element, and calls html_to_pdf. It gets the link back and downloads the PDF to out/invoice-1042.pdf. That is one PDF on your plan.

For page numbers, ask for a footer: "add 'Page X of Y' at the bottom". The tool takes a separate footer_html, and elements in it with the classes pageNumber and totalPages are filled in on every page.

Your logo has to reach the server inside the HTML or at a public address, because the server cannot read files from your disk. Ask the assistant to embed a small logo as a data: URL, or point it to the logo on your website.

Example 2: check the layout first

The assistant cannot see a PDF it made, but it can see an image. The screenshot tool returns the page as a PNG, and a screenshot under 1 MiB comes back inside the answer, so the assistant can look at it before it makes the PDF:

Build a one-page certificate for "Ana Novak, Advanced Excel, 12 October 2026" in HTML.
Take a screenshot at 1123 x 794 and check that the name is centred and nothing wraps.
Fix what is off, then make a landscape A4 PDF.

It may take two or three screenshots before the layout is right. Each screenshot counts as one PDF on your plan, the same as the final PDF, so a request like this one costs three or four. If you only need the PDF, leave the screenshot out.

Example 3: a Word file on your computer

For office_to_pdf and merge_pdfs, files go in as links. A file on your computer has none, so the assistant uploads it first:

Convert docs/contract-2026.docx to PDF and save it next to the original.

What happens:

  1. The assistant calls upload_file with the name contract-2026.docx and gets two links: one to upload to, and one to pass to the next tool.

  2. It uploads the file with curl. The upload link works for 15 minutes:

    curl -fsS -T docs/contract-2026.docx "https://mcp.pdfdispatch.com/uploads/..."

  3. It calls office_to_pdf with the second link, then downloads contract-2026.pdf into docs/.

Uploading is free; only the conversion counts. Nobody can download an uploaded file, and it is deleted after a day at the latest. Excel, PowerPoint, OpenDocument and RTF files work the same way. For only some pages, ask for them ("pages 1 to 3").

Example 4: merge files into one PDF

Results of earlier tool calls are links already, so they can go straight into merge_pdfs. Local PDFs are uploaded first, as in example 3:

Make a cover page as a PDF with the title "Q3 report" and today's date.
Then merge it with reports/q3-figures.pdf and reports/q3-notes.pdf, in that order,
into out/q3-report.pdf.

The assistant makes the cover with html_to_pdf, uploads the two local PDFs, and calls merge_pdfs with the three links in order. Two PDFs on your plan: the cover and the merge.

With office_to_pdf you can do the same in one call: several Office files with merge give one PDF instead of a ZIP.

Tips

  • Ask for print CSS: @page { size: A4; margin: 15mm; }, and break-inside: avoid on table rows and blocks that must stay together. A break-before: page on a heading starts it on a new page.
  • For notes, a README or a report without a design, say "use markdown_to_pdf". It has a clean built-in style, so the assistant does not need to write CSS.
  • Keep the key out of git. Read it from PDD_KEY or the editor's secret input. If you write .mcp.json for your team in Claude Code, use "Authorization": "Bearer ${PDD_KEY}" there, not the key itself. If a key does end up in a commit, revoke it at pdfdispatch.com/app/keys and make a new one.
  • Download results right away, because links stop working after an hour. If your project has an instructions file (CLAUDE.md, AGENTS.md, Cursor rules), add a line such as "Save PDFs from pdfdispatch into out/ with curl", and the assistant will do it every time.
  • Treat result links like the files themselves. Anyone who has one can download the file during its hour, so do not paste them into issues or chats.
  • One tool call can carry up to 10 MiB of HTML or Markdown, and an input file up to 50 MiB. Your plan's request size still applies (5 MB on the Free plan).

When something fails

Errors come back to the assistant as text it can act on. If the API refused the request, the text has its code and a link to the explanation, for example PDFDispatch refused the request (HTTP 429, code 42910): ..., where 42910 means too many requests in a minute. Requests the API refuses cost nothing, and neither does bad input the server catches first, such as an unknown paper size. All codes are in Limits and errors.

If every call fails with 401, the key did not reach the server. Check that PDD_KEY is set in the environment your editor started from.

Next