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 Streamable HTTP with Clerk OAuth (browser login) or a Bearer API key. 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. Unauthenticated requests return 401 with WWW-Authenticate resource_metadata. Cursor and Claude then complete Clerk sign-in. 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

Cursor / JSON (remote)

URL only. The host stores the OAuth token after Allow. Do not put a key in the prompt. Bearer headers still work for hosts that already have a key.

mcp.json

{
  "mcpServers": {
    "relaypdf": {
      "url": "https://api.relaypdf.com/mcp"
    }
  }
}

Bearer API key (optional)

Scripts and hosts that cannot run OAuth can send Authorization: Bearer pdf_live_…. Store the key in the host’s header or env mapping — not in chat.

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 / data / form_fields / form_fill	POST /v1/pdf/info · /text · /data · /form/*	Inspect, extract, 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

Remote: add https://api.relaypdf.com/mcp and complete Clerk login in the host. Local: relaypdf setup, then stdio MCP. Call pdf with html, url, markdown, or a published templateId.

Document and billing tools

Hosted and stdio release tools include document_ocr, document_pdfa, document_crop, document_resize, document_repair, document_optimize, document_attachments, document_extract_images, document_compress, document_image_convert, document_email, and billing_usage. Use operation-specific options from the REST guides. Tool availability depends on the deployed server or installed CLI version.

Docs hub →Node.js SDK →Playground →