PaperSprocket README

PaperSprocket MCP server

A Model Context Protocol (MCP) server that gives MCP clients direct access to the PaperSprocket API. It exposes exactly two tools:

Tool	Description
`render_html_to_pdf(html, page?)`	Render HTML to a PDF through the PaperSprocket API. Returns the PDF as an `application/pdf` MCP resource (base64 blob), a local file path when the server can write one, and render metadata (`render_id`, `page_count`, `charged_cents`, `balance_cents`). Billed to the configured account.
`check_balance(account_id)`	Read the prepaid balance of the configured PaperSprocket account. Returns `account_id`, `balance_cents`, `currency`, and `page_price_cents`.

This is a minimal native MCP server built directly on @modelcontextprotocol/sdk. No top-up tools, no API-key-management tools — just render and balance-check.

What is PaperSprocket?

PaperSprocket is a hosted API that turns HTML into PDFs. You send it HTML, it returns a well-formed PDF. There is no business-field schema to learn: you control the layout with your own HTML and CSS, PaperSprocket handles the PDF processing. See the official documentation.

Requirements

Node.js >= 20
A PaperSprocket API key. The server reads it from server-side config only (environment or .env) — it is never a caller-supplied tool argument, and is never embedded in source, examples, or this document.

Install

Run via npx (primary)

Terminal

npx -y papersprocket-mcp

The package papersprocket-mcp is published to npm and registered in the official MCP Registry under identity io.github.inde-x/papersprocket (active, version 1.0.0). Point your MCP client at npx -y papersprocket-mcp and provide PAPERSPROCKET_API_KEY in the client's environment (the server reads it server-side only).

From source (optional / development)

bash

git clone https://github.com/inde-x/papersprocket-mcp.git
cd papersprocket-mcp
npm ci
cp .env.example .env   # then set PAPERSPROCKET_API_KEY (see Configuration)

Configuration

The server loads <serverdir>/.env at startup (it does not override already-set environment variables). .env is gitignored.

Variable	Required	Default	Purpose
`PAPERSPROCKET_API_KEY`	yes	—	Your PaperSprocket API key. Secret/config state — never a tool argument.
`PAPERSPROCKET_BASE_URL`	no	`https://papersprocket.com/api`	API base URL. Fixed/config state.
`PAPERSPROCKET_MCP_OUTPUT_DIR`	no	`./output`	Directory where rendered PDFs are also written (best-effort) for filesystem-local clients.

Example .env (replace the placeholder — never commit a real key):

bash

PAPERSPROCKET_API_KEY=psk_your_api_key_here
# PAPERSPROCKET_BASE_URL=https://papersprocket.com/api
# PAPERSPROCKET_MCP_OUTPUT_DIR=./output

Run (stdio)

bash

node server.js                 # MCP over stdio
node server.js --list-tools    # print tool schemas, then exit

Connect an MCP client

Point your MCP client at a stdio server:

Code

# primary — published npm distribution:
Command:   npx
Arguments: -y papersprocket-mcp

# or a local source checkout:
Command:   node
Arguments: /path/to/papersprocket-mcp/server.js

PAPERSPROCKET_API_KEY is provided via the server .env or environment — never in the client configuration.

MCP Inspector

Terminal

npx @modelcontextprotocol/inspector node /path/to/papersprocket-mcp/server.js

List tools → confirm exactly two: render_html_to_pdf and check_balance.

Tool schemas

`render_html_to_pdf`

config.json

{
  "html": { "type": "string", "description": "HTML to render (non-empty)." },
  "page": {
    "properties": {
      "size":            { "enum": ["A4", "Letter"] },
      "orientation":     { "enum": ["portrait", "landscape"] },
      "margin_mm":       { "top|right|bottom|left": { "type": "number", "minimum": 0, "maximum": 50 } },
      "print_background": { "type": "boolean" }
    }
  }
}

html — required, non-empty string.
page — optional. Defaults mirror the service's closed v1 schema: size A4, orientation portrait, margin_mm 10 on all sides, print_background true. Unknown fields are rejected.

Result (two MCP content blocks):

text — metadata JSON: tool, format, render_id, page_count, charged_cents, balance_cents, bytes, file_path, idempotency_key.
resource — application/pdf blob (base64) with a file:// (or urn:) URI.

`check_balance`

config.json

{ "account_id": { "type": "string" } }

account_id — required, non-empty string.

Result: { account_id, balance_cents, currency, page_price_cents } (text block).

Idempotency

A fresh random idempotency key is generated for each logical render.
On a transient network failure the server retries up to 2× reusing the same key, so a retry of one logical render cannot double-charge.
Server-side, PaperSprocket dedupes on (Idempotency-Key, request hash), so a true replay returns the original result without a second debit.

Security / secret boundary

PAPERSPROCKET_API_KEY is read from .env / environment — it is not a field in any tool input schema.
PAPERSPROCKET_BASE_URL is fixed/config state, not an agent-controlled argument.
The key is sent only as the Authorization HTTP header. No other credentials exist.
Rendered PDFs written to output/ are your own content; the directory is gitignored.

Pricing

$10 initial prepaid credit
$10 top-ups
$0.02 / page

Getting a key

Create a PaperSprocket account to get your API key and prepaid credit:

Onboarding: https://papersprocket.com/onboarding/?source=mcp

License

MIT — see LICENSE.