Remote Streamable HTTP MCP

HTML-to-PDF tools for your AI agent

PixelToPdf exposes the conversion API as a native MCP server. Your agent can design print-ready HTML, render the file, and receive the PDF in the same workflow.

Your AI agent writes the HTML; PixelToPdf renders it. The API does not generate content with its own language model.

MCP endpoint

https://api.pixeltopdf.com/mcp

Authentication

Bearer API key

API key, not a separate MCP login

Sign in to the dashboard to create a key, then configure your client to send Authorization: Bearer <API_KEY> on every MCP request. X-API-Key is also accepted. A dashboard session cookie is not enough.

The key must be active, unexpired and have the convert scope. Unrestricted keys (an empty scope list) also work. Revoking a key blocks subsequent requests. There is currently no OAuth browser-login flow; clients that only support OAuth cannot connect directly.

The same conversion engine, organization credits and conversion logs are used by REST and MCP. MCP requests also have API-key rate limits, including discovery requests. Successful non-sandbox conversions consume one credit. For a free test, explicitly set sandbox: true; PDF output is watermarked.

Connect your agent

Choose a client and copy its configuration or setup prompt. Set PIXELTOPDF_API_KEY privately before launching the client, or enter it in the masked VS Code input. Never paste your secret in agent chat. Merge snippets into existing settings rather than replacing the file.

Claude Code

.mcp.json

For Claude Code, not Claude web. Set PIXELTOPDF_API_KEY in the environment before launching the client. Client documentation

{
  "mcpServers": {
    "pixeltopdf": {
      "type": "http",
      "url": "https://api.pixeltopdf.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PIXELTOPDF_API_KEY}"
      }
    }
  }
}

Codex

.codex/config.toml

The project must be trusted to load .codex/config.toml. The Codex host process must inherit PIXELTOPDF_API_KEY. Client documentation

[mcp_servers.pixeltopdf]
url = "https://api.pixeltopdf.com/mcp"
bearer_token_env_var = "PIXELTOPDF_API_KEY"
tool_timeout_sec = 180

Cursor

.cursor/mcp.json

Start Cursor with PIXELTOPDF_API_KEY available in its environment. Remote servers do not load an envFile. Client documentation

{
  "mcpServers": {
    "pixeltopdf": {
      "url": "https://api.pixeltopdf.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PIXELTOPDF_API_KEY}"
      }
    }
  }
}

OpenCode v2

opencode.jsonc

This example uses the v2 mcp.servers structure. On v1, place the pixeltopdf entry directly under mcp. Client documentation

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "pixeltopdf": {
        "type": "remote",
        "url": "https://api.pixeltopdf.com/mcp",
        "oauth": false,
        "headers": {
          "Authorization": "Bearer {env:PIXELTOPDF_API_KEY}"
        }
      }
    }
  }
}

VS Code

.vscode/mcp.json

VS Code asks for the key through a masked input. Enter it in that local input, not in the agent chat. Client documentation

{
  "inputs": [{
    "id": "pixeltopdf-api-key",
    "type": "promptString",
    "description": "PixelToPdf API key",
    "password": true
  }],
  "servers": {
    "pixeltopdf": {
      "type": "http",
      "url": "https://api.pixeltopdf.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:pixeltopdf-api-key}"
      }
    }
  }
}

Prompts never contain your key. Configure it privately in your client, never in agent chat or source control.

Available tools

generate_pdf

Converts raw HTML or a public URL into a PDF and returns it as an embedded MCP resource with its conversion ID, filename, MIME type, and size.

capture_screenshot

Renders raw HTML or a public URL as PNG or JPEG and returns image content directly to the agent.

Tool arguments

Only source is required. Use non-empty raw HTML or a public HTTP/HTTPS URL. Private/internal URLs are blocked by the renderer. Unknown fields and unsupported formats are rejected before conversion. Use camelCase option names; these are MCP arguments, not a nested REST request.

Supported MCP conversion options
ToolArguments
Both toolssource, filename (1–255 characters, no paths), sandbox, css, javascript, disableJavascript, waitForNetwork, lazyLoadImages, delay (0–10,000 ms), timeout (1–120 seconds for loading; default 30). Total conversion time may be longer.
generate_pdfformat (A0–A6, Letter, Legal, Tabloid, Ledger; default A4), landscape, usePrint, pages (e.g. 1-3), zoom (0.1–2), margin (top/right/bottom/left CSS lengths), header and footer (objects with source and optional height).
capture_screenshotoutputFormat (png or jpeg; default png), fullpage, cssSelector, quality (1–100, JPEG only). MCP does not currently expose WebP or a DPI setting.

Your client can read tools/list for the machine-readable schemas. Read them before calling a tool.

Free sandbox PDF: tools/call parameters

{
  "name": "generate_pdf",
  "arguments": {
    "source": "<!doctype html><html><body><h1>My first AI document</h1></body></html>",
    "filename": "example.pdf",
    "format": "A4",
    "margin": {
      "top": "15mm",
      "bottom": "15mm"
    },
    "sandbox": true
  }
}

Receiving and saving files

A PDF arrives in a resource content block: decode resource.blob from Base64. A screenshot arrives in an image block: decode data. Both tools return structuredContent with conversionId, filename, contentType and sizeBytes.

The pixeltopdf://conversions/… URI identifies the embedded PDF. It is not a public download URL or a stored resource: resources/read cannot retrieve it later. Save the returned bytes during the workflow.

File saving, previews and maximum response sizes depend on the client. If your client cannot save embedded binary output, use the REST API from a local script to write the response to a file. A successful tool response alone does not mean the file was saved locally.

MCP resource

pixeltopdf://docs/quickstart

A concise reference that agents can read for supported options, file handling, and recommended workflows.

MCP prompt

create_pdf_document

A reusable prompt with required purpose and content strings, plus an optional format (A4 by default). It guides HTML creation; requesting the prompt itself does not render a file or consume a conversion credit.

Connection checks and errors

  1. Restart the client after configuring its environment. Connect to /mcp using Streamable HTTP, then check that both tools appear. Discovery does not consume conversion credits.
  2. 401: missing, invalid, expired or revoked key, or an inactive account. Verify credentials locally; do not paste them in a support chat.
  3. 403: missing convert scope, inconsistent organization ownership, or a browser Origin outside the server allowlist. Native clients normally send no Origin. Browser integrations need an explicitly allowed origin.
  4. 429: API-key request limit reached. Respect the Retry-After header. Avoid automatic conversion retries because they can create additional billable conversions.
  5. Tool errors: HTTP 200 can still contain an MCP error or isError: true. Check the result before treating a conversion as successful. Invalid arguments, blocked URLs, insufficient credits and rendering failures require different fixes.
  6. Timeout or missing output: increase the client tool timeout when needed, check conversion logs before retrying, and confirm that your client supports the returned binary resource.

For self-hosting, use your API base URL plus /mcp. Set MCP_ALLOWED_ORIGINS to a comma-separated list of exact trusted browser origins. With no allowlist, requests carrying an Origin header are denied; authenticated native clients without Origin still work.

Try it with a real document

Create a free API key, connect your agent, and ask: “Turn this invoice data into a polished A4 PDF.”

Get a free API keyRead the REST API docs