Docs

MCP

Use POST https://api.relaypdf.com/mcp when the host needs a public URL (Claude, Relevance, remote Cursor). Use npx @relaypdf/cli mcp on a laptop after relaypdf setup. Agents should never ask a human to paste an API key into chat.

Two transports, same tools. Hosted MCP is Bearer Streamable HTTP. Stdio MCP is for local Cursor/Claude Desktop after relaypdf setup. Generating tools on the hosted server return a 24-hour URL — not filesystem paths and not raw bytes.

Hosted (Streamable HTTP)

POST https://api.relaypdf.com/mcp with Authorization: Bearer. Initialize, tools/list, and tools/call are JSON-RPC. File inputs are https URLs or base64 file. Prefer a previous tool’s url as the next input. async: true returns a job id; poll with jobs_get or jobs_wait.

Claude Code

claude mcp add --transport http relaypdf https://api.relaypdf.com/mcp \
  --header "Authorization: Bearer $RELAYPDF_API_KEY"

Cursor / JSON (remote)

Put the key in the host’s header or env mapping — not in the prompt. OAuth is not shipped yet.

mcp.json

{
  "mcpServers": {
    "relaypdf": {
      "url": "https://api.relaypdf.com/mcp",
      "headers": {
        "Authorization": "Bearer pdf_live_…"
      }
    }
  }
}

Stdio (local CLI)

Uses the same local credentials as CLI commands (~/.config/relaypdf/credentials.json or RELAYPDF_API_KEY). Binary tools require out (a filesystem path).

Start

npx @relaypdf/cli mcp

Cursor example (stdio)

Point an MCP server entry at npx after relaypdf setup.

mcp.json

{
  "mcpServers": {
    "relaypdf": {
      "command": "npx",
      "args": ["-y", "@relaypdf/cli", "mcp"]
    }
  }
}

Tools

Same names on hosted and stdio. Hosted generating tools return JSON with a 24h url. Stdio binary tools still take out.

Tool	HTTP	Notes
pdf	POST /v1/pdf	html, url, markdown, or templateId + templateData
image	POST /v1/images	html or url; fullPage; type
convert	POST /v1/convert	html, url, or file + sourceFilename; to
merge / extract / protect / unlock	POST /v1/pdf/*	PDF tools
raster / from_images / stamp / rotate / delete_pages / compress	POST /v1/pdf/*	More PDF tools
info / text / form_fields / form_fill	POST /v1/pdf/info · /text · /form/*	Inspect and fill
barcode	POST /v1/barcodes	type + text
zip	POST /v1/zip	Named files
templates_list / gallery / create / publish	/v1/templates	Handlebars
webhooks_list / create / delete	GET/POST/DELETE /v1/webhooks	Signed endpoints; secret on create only
jobs_get / jobs_wait	GET /v1/jobs/:id	Async
health	GET /health	Liveness

Recommended flow

Local: relaypdf setup, then stdio MCP. Remote: store RELAYPDF_API_KEY in the host config and call pdf with html, url, markdown, or a published templateId.

Docs hub →Node.js SDK →Playground →