MCP server

The CastPDF MCP server lets you use CastPDF from AI agents (Claude, Cursor, ChatGPT and others that support MCP). Ask in plain words, and the agent lists your templates, reads the fields a template expects, creates a PDF or an EU e-invoice, and looks up your documents, using your CastPDF API key. It is the package @castpdf/mcp on npm, version 0.1.0, MIT licensed, from github.com/castpdf/castpdf-mcp, and it is listed in the official MCP registry as io.github.castpdf/castpdf-mcp.

What MCP is

The Model Context Protocol (MCP) is an open standard for connecting AI agents to tools and data. An MCP server describes a set of tools: their names, what they do and the input each one takes. The agent's app (the MCP client) starts the server, shows its tools to the model, and runs a tool when the model asks for it. The CastPDF MCP server is a small Node.js program that turns each tool call into a request to the CastPDF API with your key, and returns the answer to the agent.

The agent never sees your key, and the files never pass through the conversation: a tool returns a signed download link that expires, and the agent shares the link with you.

Before you start

• Node.js 20 or newer, so that npx can start the server. Check with node --version.
• A CastPDF API key. In the dashboard, open Connect, then API, and create a key. A test key (cpdf_test_) makes free, watermarked documents (test and live mode).
• At least one template, if you want the agent to fill your own designs. Without one it can still render HTML or issue an e-invoice with the built-in layout.

The server reads the key from the CASTPDF_API_KEY environment variable. Each client below sets it in its own configuration.

Claude Desktop

Open Settings, then Developer, then Edit Config, and add the server to claude_desktop_config.json:

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

Restart Claude Desktop. On Windows, if npx is not found, use "command": "cmd" and "args": ["/c", "npx", "-y", "@castpdf/mcp"].

Claude Code

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

Add --scope user to use it in every project. Check it with claude mcp list, or with /mcp inside Claude Code.

Cursor

Add the server to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

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

Do not commit a file that contains your key. For a project file, keep it out of version control or use the user-level file.

VS Code

Add the server to .vscode/mcp.json in your workspace. The inputs entry makes VS Code ask for the key once and store it, so the key is not written into the file:

{
  "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}" }
    }
  }
}

Start the server from the file, then use it from the chat in agent mode.

Other clients

Any MCP client that starts local (stdio) servers works with the command npx -y @castpdf/mcp and the environment variable CASTPDF_API_KEY. Clients that connect over HTTP use the HTTP mode below.

The tools

The usual flow is list_templates, then get_template_fields to learn the data shape, then create_pdf with the template id and the data. Each tool calls the API with your key, so the limits of your plan apply: test documents are free, and a live document counts like one made from your own code (usage and billing).

Prompts that work well:

• "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."
• "Did my last document fail? Why?"

Test mode by default

create_pdf and create_e_invoice send "test": true unless you clearly ask for a live, final document, and the tool descriptions tell the agent to do exactly that. A test document is watermarked and never counts toward your plan. With a test key, every document is a test document whatever the agent sends, so a test key is the safe choice while you try things out. Switch to a live key only when you want the agent to make real documents.

Security

• The key stays with the server. It is read from the environment and sent only to the CastPDF API. The model never receives it.
• Use a test key to start. A test key cannot make live documents, so nothing counts and every document carries the watermark.
• Keep keys out of shared files. Do not commit a configuration file that holds a key. VS Code's inputs and Claude Code's --env keep it out of your project.
• Read what the agent sends. Clients show each tool call and its input before or as it runs. Check the data in a create_pdf or create_e_invoice call, as you would check a form before you submit it.
• Revoke a key you no longer trust in the dashboard. The server then gets invalid_api_key and makes nothing (authentication).

The HTTP mode

For clients that connect over HTTP, or to run one shared server, start it with --http:

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

Then point the client at the endpoint, for example in Claude Code:

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

Every request to that endpoint uses the server's API key, so the HTTP mode is locked down by default:

• It listens on 127.0.0.1 only, accepts only localhost, 127.0.0.1 and [::1] as the Host header (protection against DNS rebinding), and refuses requests from a browser origin.
• Set CASTPDF_MCP_AUTH_TOKEN to require Authorization: Bearer <token> on every request. It is required before the server listens on any other interface (--host 0.0.0.0). Put a proxy that terminates TLS in front of it, and list the public host name in CASTPDF_MCP_ALLOWED_HOSTS.
• The server is stateless (no sessions, POST only), so it can run behind a load balancer.

Next steps

• CastPDF MCP server overview: what an agent can do with it, and how the pieces fit.
• SDKs for Node.js and Python: the same API from your own code.
• Templates and versions: the templates the agent fills.
• E-invoicing guide: the standards behind create_e_invoice.