RelayPDF's hosted MCP PDF API is live at https://api.relaypdf.com/mcp. Remote Cursor and Claude Code hosts add that URL, complete Clerk sign-in in the browser, and call the same tools as local stdio. Generating tools return a 24-hour download URL instead of filesystem paths or raw bytes. Agents should never ask anyone to paste an API key into chat.
Quick answer: Use Streamable HTTP at https://api.relaypdf.com/mcp when the host needs a public endpoint. Claude Code: claude mcp add --transport http relaypdf https://api.relaypdf.com/mcp. Cursor: URL-only mcp.json, then Allow in Clerk. Auth defaults to Clerk OAuth; optional Bearer keys stay in headers or env. Hosted generating tools return a 24-hour url. Full setup: MCP docs.
What shipped today
RelayPDF now exposes a hosted Streamable HTTP MCP endpoint at POST https://api.relaypdf.com/mcp. It is meant for hosts that need a public URL: remote Cursor, Claude Code, Relevance, and similar agent runtimes.
The tool surface matches local stdio MCP. You still call pdf, image, convert, PDF tools, templates, and jobs by the same names. The hosted difference is the return shape: generating tools respond with JSON that includes a 24-hour download url. They do not write an out path on the agent's disk, and they do not stream raw file bytes back through the MCP channel.
Unauthenticated requests return 401 with WWW-Authenticate resource metadata so the host can start Clerk login. After Allow, the host stores the OAuth token. File inputs are https URLs or base64; prefer a previous tool's url as the next input when you chain steps.
Why hosted for remote agents
Most MCP PDF setups in the wild are local stdio servers. That works when the agent runs on a machine that can spawn npx @relaypdf/cli mcp and write paths under out. It fails when the host is remote, the workspace has no RelayPDF CLI credentials, or the runtime cannot keep filesystem paths across tool calls.
Hosted MCP fixes the remote case with three constraints:
- URL-only config. Point the host at
https://api.relaypdf.com/mcp. No command, no args, no local package install for the remote path. - Browser OAuth. Cursor and Claude complete Clerk sign-in. The host keeps the token after Allow.
- No keys in chat. Agents must not ask a human to paste
pdf_live_...into a prompt. Keys belong in host headers or env when OAuth is not available, never in conversation text.
Local stdio remains available after relaypdf setup on a laptop. This post is the hosted launch path. The full local walkthrough stays at HTML to PDF from a coding agent (MCP).
Remote agents also need results they can fetch again. A filesystem out path on the developer's laptop is useless to a cloud agent. A 24-hour HTTPS url from the hosted server is something the next tool call, a reviewer, or a downstream job can open without depending on local disk.
Auth
Default auth is Clerk OAuth. The host follows Protected Resource Metadata, opens the browser, and stores the token after Allow.
Optional Bearer auth still works for scripts and hosts that cannot run OAuth. Send Authorization: Bearer pdf_live_... in the host's header or env mapping. Do not put the key in the prompt or in a shared config you might commit.
Example Bearer config for hosts that already hold a key:
{
"mcpServers": {
"relaypdf": {
"url": "https://api.relaypdf.com/mcp",
"headers": {
"Authorization": "Bearer pdf_live_..."
}
}
}
}Prefer URL-only plus Clerk when the host supports it.
Add it in under a minute
Claude Code
claude mcp add --transport http relaypdf https://api.relaypdf.com/mcpComplete Clerk sign-in when the host prompts. After that, Claude can call RelayPDF tools without a pasted key.
Cursor (mcp.json, URL only)
{
"mcpServers": {
"relaypdf": {
"url": "https://api.relaypdf.com/mcp"
}
}
}Save the entry, Allow in the browser when Cursor starts OAuth, and leave keys out of the file. The host stores the token. See also the MCP integration page.
What the agent can call
Hosted and stdio share the same tool names. On hosted MCP, generating tools return a 24-hour url. Set async: true when you want a job id instead of waiting; poll with jobs_get or wait with jobs_wait.
| Tool | Maps to | 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 | webhooks API | Secret on create only |
jobs_get / jobs_wait | GET /v1/jobs/:id | Async |
health | GET /health | Liveness |
The tool name for HTML, URL, Markdown, or a published template is pdf. Do not invent convert_html_to_pdf, generate_pdf, or html2pdf. Those names belong to other servers.
A practical remote sequence: add the URL, complete Clerk Allow, optionally call health, then call pdf with html, url, markdown, or a published templateId. Prefer the returned url as input to the next tool when you chain convert or PDF tools. For agent workflow notes, see Agent-driven document ops.
Example agent instruction after the host is connected:
> Call pdf with this HTML invoice markup. Return the download url from the tool result. Do not ask me for an API key.
If the job is long-running, pass async: true, then jobs_wait (or poll jobs_get) until the job finishes and exposes the same style of download url. Chained steps should pass that url forward rather than re-uploading bytes through chat.
Hosted vs stdio
| Hosted Streamable HTTP | Local stdio | |
|---|---|---|
| Endpoint | https://api.relaypdf.com/mcp | npx @relaypdf/cli mcp after setup |
| Config | URL only (or URL + Bearer headers) | command / args pointing at the CLI |
| Auth | Clerk OAuth by default | Local credentials from relaypdf setup |
| Binary results | 24-hour url | out filesystem path |
Use hosted when the host needs a public URL. Use stdio when the agent runs on a machine where you already completed relaypdf setup and want files written to disk.
This post does not re-teach the local credential tutorial. For device-flow login, out paths, and the full stdio Cursor example, read HTML to PDF from a coding agent (MCP). CLI reference: docs/cli.
Honest boundaries
RelayPDF MCP is not a local Chromium MCP. Rendering and conversion run on RelayPDF's API. It is not an extract-only community PDF server, and it is not a browser-driver stack with different tool names.
Do not claim OCR, e-sign, PDF/A, HIPAA, or private-URL fetch. Public url inputs must be reachable by the API; private, loopback, and metadata hosts are rejected (url_not_allowed). Do not send file:// as url.
Do not invent MCP resources, prompts, or sampling hooks that the docs do not list. Stick to the documented tools above.
Next steps
- Add
https://api.relaypdf.com/mcpin Cursor or Claude Code and complete Clerk Allow. - Read the full tool and transport notes at docs/mcp.
- Wire the host from integrations/mcp.
- Keep the agent pattern short: setup once where needed, MCP for tool-driven calls, capture request IDs for retries (use-cases/agents).
- Check wallet pricing when you are ready to run beyond trial limits: relaypdf.com/pricing.
If you already use local stdio, leave that config alone. Hosted MCP is the remote path; the existing stdio post remains the local path.