Developer documentation

Turn Markdown into a designed, print-ready PDF from your own code, from an MCP client, or from a conversation with Claude. Three ways in, one conversion, one balance.

Getting started Authentication Endpoints Options Errors Rate limits MCP server Claude Skill

Getting started

One conversion costs one credit. A failed conversion costs nothing — the credit is spent only once the PDF exists, so a rejected request, an invalid option or a conversion error is never charged. API keys have no free monthly allowance; that is for browser use.

Base URL. The API is served from the same origin as this page. The examples below use $MDPRINT_API_URL for it — set that to the origin in your address bar. The MCP server and the skill read the same variable, and both default to the hosted service.

curl -X POST $MDPRINT_API_URL/api/v1/convert \
  -H "Authorization: Bearer $MDPRINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello\n\nMy first document.", "theme": "default", "mode": "report"}'
{
  "download_url": "https://…/api/download/<token>/hello.pdf",
  "expires_in": 300,
  "filename": "hello.pdf",
  "bytes": 214512,
  "credits_remaining": 41
}

Download links live for five minutes. Fetch the file promptly, or convert again.

Authentication

Send your key as a bearer token on every request:

Authorization: Bearer mdp_sk_…

Keys are shown once, when they are created, and stored only as a hash — we cannot recover one for you. Revoking a key takes effect immediately. Treat a key like a password: it spends real credits.

Do not have a key yet? Get in touch — keys are issued on request while the self-service key management page is being built.

Endpoints

Endpoint What it does
POST /api/v1/convert Markdown and options in, a PDF out. Spends one credit on success.
GET /api/v1/credits Credits remaining on the key's account.
GET /api/v1/themes Every theme, document mode, colour scheme, paper size and drop-cap style that exists. Read this rather than guessing values.
GET /api/v1/openapi.json The OpenAPI 3.1 description of this API. No key required, so a tool can read the contract before it has one.

Conversion options

markdown is the only required field. Everything else has a sensible default, and every permitted value is listed by GET /api/v1/themes.

Field Default Notes
markdown — The document. Up to 2 MB.
theme default fantasy for tabletop material, default for everything else.
mode standard Document type: report, newsletter, newspaper-times, newspaper-tabloid, resume, certificate, poem.
paper A4 Letter, Legal and Tabloid also available.
columns 1 (2 for fantasy) One or two columns.
colors classic Colour scheme. Fantasy theme only.
dropCapStyle — Decorative first letter. Fantasy theme only.
output url base64 returns the PDF inline instead. See the note below.
config — Advanced typography and layout overrides.

Prefer output: "url". A multi-megabyte base64 string is expensive to move and, in an LLM context window, expensive in a way that is hard to undo — an agent that inlines every PDF exhausts its context by the third document. Use base64 only when your client genuinely cannot follow a link.

Errors

Every error has the same shape. Branch on code, never on the message text.

{ "error": { "code": "insufficient_credits", "message": "…", "docs_url": "…" } }
Status Code What to do
400 invalid_request An option or the Markdown was malformed. Fix it and retry.
401 invalid_key Missing, unknown or revoked key. Stop; do not retry.
402 insufficient_credits The account is out of credits. Stop and top up.
404 not_found No such endpoint. Check the path.
405 method_not_allowed Wrong method; the Allow header names the right one.
413 payload_too_large Over 2 MB. Split the document and convert the parts.
429 rate_limited Rate or concurrency limit reached. Wait for Retry-After, then retry once.
500 conversion_failed The conversion failed. No credit was spent. Retry once, then stop.
503 metering_unavailable The API is not accepting requests. Stop and try later.

Rate limits

Each key has an hourly conversion allowance — 60 by default, raisable on request — refilled continuously rather than in one hourly jump. Reads (/credits, /themes) draw on a separate, much larger allowance, so polling your balance never eats into conversions. There is also a cap on how many conversions may run at once per key: each one is a real typesetting pass, and a refused slot comes back as rate_limited rather than queueing.

Every response carries the numbers, so you never have to guess:

X-Credits-Remaining: 147
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1756650000
Retry-After: 30          (429 only)

MCP server

An MCP server exposes the conversion as tools to any MCP client. It is a thin client over the API above and holds no conversion logic of its own; the key comes from its environment.

Claude Desktop

Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "grimoireprint": {
      "command": "npx",
      "args": ["-y", "@mdprint/mcp-server"],
      "env": { "MDPRINT_API_KEY": "mdp_sk_…" }
    }
  }
}

Claude Code

claude mcp add grimoireprint --env MDPRINT_API_KEY=mdp_sk_… -- npx -y @mdprint/mcp-server

Restart the client afterwards. Three tools appear: convert_markdown_to_pdf, list_themes and get_credit_balance. Conversions return a link to the PDF; passing embed_pdf: true returns the file inline instead, at the cost described above. Running out of credits, a bad key or a rate limit come back as ordinary tool errors with what to do about them, not as protocol failures.

stdio only. The MCP specification says stdio servers should take credentials from the environment rather than run an OAuth flow, which is what this does. A remote HTTP endpoint would need full OAuth 2.1, so it is not offered rather than shipped as a deviation.

Claude Skill

If you would rather ask in plain language than call a tool, install the skill from skills/markdown-to-pdf/ in the repository:

Set MDPRINT_API_KEY in the same environment the client runs in, then ask for a PDF. The skill chooses a theme and document mode from the kind of document you are making, checks the live option list rather than guessing, and hands back a download link.

Back to the converter