Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@papertype-mcp turn this markdown into a PDF saved as ~/Documents/q3-report.pdf"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for PaperType, a hosted PDF API. It lets Claude Desktop, Claude Code, Cursor and any other MCP client turn Markdown, HTML or a filled-in template (invoice, certificate, report) into a PDF file on your disk.
The server runs locally over stdio, calls https://papertype.dev/v1/pdf with your API key, and
writes the PDF to a file. It returns the file path, page count and your remaining quota; it never
returns PDF bytes to the model.
Clients are open source (MIT); the rendering service is hosted and paid above the free tier.
API reference: https://papertype.dev/docs
Get an API key: https://papertype.dev/signup?ref=npm
Python SDK and CLI: pip install papertype
Node.js 20 or newer (uses the built-in fetch).
A PaperType API key (dp_...) from https://papertype.dev/signup?ref=npm.
Related MCP server: docrenders-mcp
Environment variable | Required | Default | Meaning |
| yes | — | Your API key. The server refuses to start without it and prints where to get one. |
| no |
| API origin; change only for self-hosted or test deployments. |
| no |
| Where PDFs are written when a call gives no |
Files in the temp directory may be cleaned up by the OS; set PAPERTYPE_OUTPUT_DIR to a
persistent folder (for example ~/Documents/papertype) if you want to keep them.
Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows:
%APPDATA%\Claude\) and restart Claude Desktop:
{
"mcpServers": {
"papertype": {
"command": "npx",
"args": ["-y", "papertype-mcp"],
"env": {
"PAPERTYPE_API_KEY": "dp_...",
"PAPERTYPE_OUTPUT_DIR": "/Users/you/Documents/papertype"
}
}
}
}claude mcp add papertype -e PAPERTYPE_API_KEY=dp_... -- npx -y papertype-mcpAdd -e PAPERTYPE_OUTPUT_DIR=/path/to/folder to choose where PDFs land. Check with claude mcp list.
Settings → MCP → Add new global MCP server, or create .cursor/mcp.json in your project:
{
"mcpServers": {
"papertype": {
"command": "npx",
"args": ["-y", "papertype-mcp"],
"env": { "PAPERTYPE_API_KEY": "dp_..." }
}
}
}Run the command npx -y papertype-mcp (or install globally with npm i -g papertype-mcp and run
papertype-mcp) with PAPERTYPE_API_KEY in its environment. The server speaks MCP over
stdin/stdout; diagnostics go to stderr. papertype-mcp --help prints the options.
render_pdfRender a document and save it as a PDF. Give exactly one source:
markdown — GitHub-flavoured Markdown (tables, fenced code, footnotes, admonitions), or
html — an HTML document or fragment, or
template + data — one of invoice, certificate, report with a JSON object of fields.
Optional: theme (clean default, report, minimal, letter, none), page_size (A4
default, Letter, Legal, A5), title, author, date, cover, toc (Markdown only),
page_numbers (default true), header, footer, css, filename, and output_path.
output_path rules: omit it to get a unique file named after the title (or filename, or the
first Markdown heading) under PAPERTYPE_OUTPUT_DIR, never overwriting anything; pass an
existing directory (or a path ending in /) to save a uniquely named file in it; pass any other
path to write exactly that file (.pdf is appended if missing and an existing file is replaced).
Relative paths resolve against PAPERTYPE_OUTPUT_DIR.
Returns text like:
Saved PDF: /tmp/papertype/q3-report.pdf
Pages: 4
Quota this month: 12 of 50 documents used (free plan)
Note: free plan output carries a small papertype.dev mark.Each successful call uses one document of the account's monthly quota.
list_templatesLists the three hosted templates with a description, every field (name, type, required) and a
complete sample data object. Local only; no quota used. Live pages:
https://papertype.dev/templates/invoice, /templates/certificate, /templates/report.
accountReturns GET /v1/me: email, plan, quota, used_this_month, watermark. No quota used.
API failures come back as tool errors (isError: true) that include the server's own message:
HTTP | Meaning |
401 | Missing or invalid API key — check |
400 | No |
413 | Source larger than 2 MB. |
422 | Render or template error; the detail says which field or construct failed. |
429 | Monthly document quota reached; upgrade at https://papertype.dev/account. |
Network failures and timeouts are reported the same way, with the URL that was tried.
Free-plan PDFs carry a small papertype.dev mark in the footer; paid plans do not. The server
checks /v1/me once per process and appends a note to render_pdf results when the mark
applies, so the model (and you) are not surprised by it.
2 MB of source and 300 pages per document. Renders are processed a couple at a time server-wide, so a call can take several seconds under load; the client waits up to 3 minutes. Rendering is CSS paged media (WeasyPrint); no JavaScript runs. See https://papertype.dev/docs.
npm install
npm run build # tsc -> dist/
npm test # vitest, fetch is mocked; no network or API key needed
PAPERTYPE_API_KEY=dp_... node dist/cli.jsSource layout: src/cli.ts (entry point, stdio transport), src/server.ts (tool definitions),
src/client.ts (fetch wrapper for /v1/pdf and /v1/me), src/errors.ts (status → message),
src/output.ts (file naming), src/templates.ts (template catalogue copied from the service's
doc_templates/*/meta.json and sample.json; keep it in sync when templates change).
npm: bump version in package.json and src/version.ts (a test checks they match), then
npm publish. prepublishOnly runs the build and tests.
MCP Registry (https://registry.modelcontextprotocol.io): server.json in this folder follows
the 2025-12-11 server.json schema and validates against it. Publishing additionally
requires: (1) proving ownership of the dev.papertype/* namespace with the mcp-publisher CLI
(mcp-publisher login dns or login http for papertype.dev; a GitHub-based namespace such as
io.github.<owner>/papertype-mcp would use login github instead, and name plus
mcpName below must then be changed to match), (2) the npm package containing an
"mcpName": "dev.papertype/papertype-mcp" field in package.json so the registry can confirm
the package belongs to that namespace, and (3) mcp-publisher publish run from this folder after
the npm version is live. The registry's rules can change; run mcp-publisher validate (or the
schema check in npm run check:manifest) before each publish rather than trusting this note.
MIT. See LICENSE. "PaperType" refers to the hosted service at papertype.dev; this package is the
client, not the renderer.
Show the PaperType account behind the configured API key: email, plan, monthly document quota, documents used this month, and whether output carries the free-plan mark. Uses no quota.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower; the description still adds non-obvious context — that it operates on the configured API key and consumes no quota.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero waste; the field enumeration is informative rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by naming the exact returned fields (email, plan, quota, usage, free-plan mark), which is everything an agent needs to know before calling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Show the PaperType account behind the configured API key') and enumerates the returned fields, so its function is unmistakable against siblings render_pdf and list_templates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied (check identity, plan, quota status) and the 'Uses no quota' note hints it's safe to call freely, but there is no explicit when-to-use/when-not guidance or named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the hosted PDF templates available to render_pdf (invoice, certificate, report) with a description, the fields each accepts (name, type, required) and a complete sample data object you can adapt. No network call; uses no quota.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent, non-destructive), the description adds key behavioral details: it performs no network call and consumes no quota, and it returns descriptions, field definitions, and complete sample data. This is valuable context that annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and return contents, followed by a concise note on cost. Every sentence provides useful information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema) and the rich annotations already covering safety, the description provides everything an agent needs: what it returns, which sibling it supports, and that it is free of network/quota costs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to clarify. The baseline for zero parameters is 4, and the description appropriately does not waste words on non-existent parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List') and resource ('hosted PDF templates'), and explicitly links to the sibling tool render_pdf by naming the templates it makes available. An agent can immediately understand that this tool discovers templates for later rendering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used before calling render_pdf to discover available templates, and it notes 'No network call; uses no quota,' which helps an agent choose it freely. However, it does not explicitly state when not to use it or compare it to alternatives beyond the implicit link to render_pdf.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a PDF from Markdown, HTML, or a hosted template (invoice, certificate, report) using the PaperType API, and save it to disk. Returns the absolute file path, page count and remaining quota; the PDF bytes are never returned inline. Provide exactly one source: markdown, html, or template + data. Each call uses one document of the account's monthly quota.
| Name | Required | Description | Default |
|---|---|---|---|
| css | No | Extra CSS appended after the theme (markdown/html). May include @page rules, e.g. '@page { margin: 2cm }'. | |
| toc | No | Add a table of contents built from headings. Markdown input only. Default false. | |
| data | No | JSON object of fields for the chosen template (required when template is set). Shape per template is shown by list_templates. | |
| date | No | Date text shown on the cover page, e.g. '2026-10-18' or 'October 2026'. | |
| html | No | HTML document or fragment to render. A theme wraps it in page styles unless theme is 'none'. Provide exactly one of markdown, html, or template+data. | |
| cover | No | Add a cover page with title, author and date (markdown/html). Default false. | |
| theme | No | Page style for markdown/html input. 'clean' (default, general documents), 'report' (formal, good with cover+toc), 'minimal' (plain), 'letter' (correspondence), 'none' (HTML only: no theme, just your own CSS). Ignored for templates. | |
| title | No | Document title: used for the PDF metadata, the cover page, and the default output filename. | |
| author | No | Author shown on the cover page and in PDF metadata. | |
| footer | No | Footer text printed bottom-left on every page (e.g. a confidentiality note). | |
| header | No | Running header text printed top-right on every page. | |
| filename | No | Suggested file name (e.g. 'invoice-014.pdf'). Used for the saved file's name when output_path is not given. | |
| markdown | No | Markdown source for the document (GitHub-flavoured: headings, lists, tables, fenced code, footnotes, admonitions). Provide exactly one of markdown, html, or template+data. | |
| template | No | Name of a hosted template to fill with `data` instead of writing markdown/html: 'invoice', 'certificate' or 'report'. Call list_templates to see each template's fields and sample data. | |
| page_size | No | Paper size. Default A4. Use 'Letter' for US documents. | |
| output_path | No | Where to save the PDF. Omit to get a unique file named after the title under the server's output directory (PAPERTYPE_OUTPUT_DIR, default <tmp>/papertype). An existing directory (or a path ending in '/') saves a uniquely named file inside it. Any other path is used as the exact file name ('.pdf' appended if missing; an existing file is overwritten). Relative paths resolve against the output directory. | |
| page_numbers | No | Print page numbers in the footer. Default true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly=false, openWorld=true, idempotent=false, and destructive=false. The description adds useful behavioral detail beyond annotations: it returns the absolute file path, page count, and remaining quota, explicitly says PDF bytes are never returned inline, and flags quota consumption. It omits overwrite behavior, though the output_path schema covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four tight sentences with no wasted language. The core action and output behavior are front-loaded, followed by source constraints and quota impact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 17-parameter tool with no output schema, the description does well: it explains return values, quota consumption, and source constraints. It could be slightly more complete by explicitly pointing template users to list_templates for data shape, but the schema already contains that pointer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 17 parameters in detail, including the exactly-one-source rule. The description restates the mutual exclusivity of markdown/html/template+data and names the template types, but adds little parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Render a PDF'), names the three supported source types, and specifies that the result is saved to disk. That is enough for an agent to distinguish this tool from list_templates and account without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for source selection ('provide exactly one source') and notes that each call consumes one monthly document quota. It does not explicitly say when to use this tool versus siblings or when not to use it, but the operational context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0accountlist_templatesrender_pdfScored across 3 tools
The three tools have clearly distinct purposes: rendering a document, listing available templates, and inspecting account/quota status. There is no overlap in selection intent, and list_templates explicitly supports render_pdf without competing with it.
render_pdf and list_templates follow a clear verb_noun pattern, while account is a noun-only name. The deviation is minor and still readable, but it prevents a perfect consistency score.
Three tools are well-scoped for a focused PDF rendering service. Each tool earns its place: rendering, template discovery, and account/quota inspection.
The surface covers the core lifecycle: discovering templates, rendering documents, and checking quota/account state. Minor gaps exist, such as no separate template-detail or validation operation, but list_templates largely mitigates this.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Convert PDF documents to Markdown for AI agents through an authenticated remote MCP server.
MCP server for Api2Pdf — generate PDFs & images from HTML, URLs or office files; merge, barcodes.
Design, publish and render PDF templates with Typst. Full template lifecycle over MCP.
