The CastPDF MCP server: PDFs from your AI agent

01What the MCP server does

The Model Context Protocol (MCP) is an open standard that lets an agent use outside tools. An MCP server lists its tools, with a name, a description and the input each one takes. The agent’s app (the MCP client) starts the server, shows the tools to the model, and runs one when the model decides it is needed. The CastPDF MCP server is a small Node.js program that offers six tools, and turns each call into an ordinary request to the API.

Nothing new runs on our side: the tools use the same endpoints as your own code, with the same limits and the same plan. The model never sees your API key, and the file never travels through the conversation. A tool returns a private link, and the agent shares that link with you.

02Set it up in a few minutes

1. Create a test key. In the dashboard, open Connect, then API, and create a key that starts with cpdf_test_. Test documents are free and carry a watermark.
2. Add the server to your client. Paste the configuration for your client below, with your key in CASTPDF_API_KEY. You need Node.js 20 or newer for npx.
3. Restart the client. The client starts the server and lists its six tools. In Claude Code, /mcp shows whether it is connected.
4. Ask for a document. Try "Which CastPDF templates do I have?", then ask for a test PDF of one of them with your own data.

{
  "mcpServers": {
    "castpdf": {
      "command": "npx",
      "args": ["-y", "@castpdf/mcp"],
      "env": { "CASTPDF_API_KEY": "cpdf_test_..." }
    }
  }
}

claude mcp add castpdf --env CASTPDF_API_KEY=cpdf_test_... -- npx -y @castpdf/mcp

{
  "mcpServers": {
    "castpdf": {
      "command": "npx",
      "args": ["-y", "@castpdf/mcp"],
      "env": { "CASTPDF_API_KEY": "cpdf_test_..." }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "castpdf-api-key", "description": "CastPDF API key", "password": true }
  ],
  "servers": {
    "castpdf": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@castpdf/mcp"],
      "env": { "CASTPDF_API_KEY": "${input:castpdf-api-key}" }
    }
  }
}

Claude Desktop reads claude_desktop_config.json (Settings, Developer, Edit Config). Cursor reads ~/.cursor/mcp.json for every project or .cursor/mcp.json for one. VS Code reads .vscode/mcp.json, and its inputs entry asks for the key once instead of keeping it in the file. On Windows, if Claude Desktop cannot find npx, start it through cmd /c. The setup guide covers each client in detail.

03The six tools

A good agent follows the order the server suggests: it lists your templates, reads the fields of the one you want, and only then calls create_pdf with data in the right shape. That is why it rarely guesses a field name. The e-invoice tool computes the totals and the VAT from the lines, following the EN 16931 rules, so the agent never adds up money itself. More on the formats is in the e-invoicing overview.

04What you can ask

• "Which CastPDF templates do I have?"
• "Make a test PDF of the Invoice template for Ada Lovelace: 3 hours of consulting at 120 EUR."
• "Create a ZUGFeRD invoice from Muster GmbH to Kunde AG for 8 hours of consulting at 95 EUR plus 19% VAT, payable in 14 days."
• "Did my last document fail? Why?"
• "Render this HTML table as a landscape A4 PDF."

1. YouMake a test invoice for Ada Lovelace, 3 hours of consulting at 120 EUR.
2. AgentCalls list_templates and finds "Invoice", then get_template_fields to learn its fields.
3. AgentCalls create_pdf with the template id, the data and test: true.
4. CastPDFRenders the PDF and returns a signed link that expires.

The agent works with your saved templates and your data. It does not design templates for you: you build those in the dashboard editor, or start from one of the free templates.

05Test documents unless you say otherwise

Agents try things. So create_pdf and create_e_invoice send "test": true unless you clearly ask for a live, final document, and their descriptions tell the agent to keep it that way. A test document is watermarked and never counts toward your plan.

• A cpdf_test_ key can never make a live document, whatever the agent sends.
• With a live key, a live document still needs your explicit request, such as "make the final invoice".
• Live documents count like any other: one per document, whatever its page count (pricing).
• Every document shows up in your dashboard and in list_documents, so nothing is made out of sight.

06Security

• The key stays with the server. It is read from the environment and sent only to the CastPDF API, never to the model.
• Start with a test key. It cannot make live documents, so a mistake costs nothing.
• Keep keys out of shared files. Never commit a config file that holds a key; VS Code inputs and the Claude Code command keep it out of your project.
• Read the tool calls. Clients show each call and its input. Check the data in a create_pdf call the way you would check a form.
• Revoke a key in the dashboard when you stop using it. The server then gets invalid_api_key and makes nothing.

07Run it over HTTP

Most clients start the server themselves over stdio. For a client that connects over HTTP, or for one shared server, start it with --http. It then serves Streamable HTTP at /mcp and a health check at /health.

CASTPDF_API_KEY=cpdf_test_... npx -y @castpdf/mcp --http --port 3000
# MCP endpoint: http://127.0.0.1:3000/mcp

claude mcp add --transport http castpdf http://127.0.0.1:3000/mcp

Every request to that endpoint uses the server's key, so the HTTP mode is locked down by default. It listens on 127.0.0.1 only, checks the Host header against the localhost names, and refuses browser origins. To listen on another interface you must set CASTPDF_MCP_AUTH_TOKEN, which every request then sends as a bearer token; put a proxy with TLS in front, and list the public host in CASTPDF_MCP_ALLOWED_HOSTS. The server keeps no sessions, so it runs fine behind a load balancer.

08MCP server, SDK or plain HTTP?

All three use the same API key, the same templates and the same plan. A common path is to try a template from the agent first, then move the same request into your code with the Node.js or Python SDK. The quickstart shows the first request without either.

09Common questions

10More developer guides

• DevelopersNode.jsThe official @castpdf/sdk or one fetch call, no Puppeteer or Chromium to install.
• DevelopersExpressAn Express route and error middleware around one fetch call, written as ESM.
• DevelopersNext.jsApp Router Route Handlers and Server Actions that return PDFs, no browser bundled.
• DevelopersFirebaseA 2nd gen Cloud Function on Node 20 that renders a PDF and saves it to Cloud Storage.
• DevelopersAWS LambdaA Node 20 Lambda handler that renders a PDF, writes it to S3 and returns a presigned link.