AI agents & MCP

These docs are built to be consumed by AI agents — ChatGPT, Claude, Cursor, and MCP-capable assistants — not just humans. Everything on this page is a load-bearing contract for how machines should read and act on PixlDocs.

Machine-readable index — /llms.txt

We publish an llms.txt at https://www.pixldocs.com/llms.txt. It is a small markdown file that tells crawlers what PixlDocs is and lists every public page and doc worth reading. Point an agent at that URL and it can walk the whole surface without parsing the JS shell.

curl https://www.pixldocs.com/llms.txt

Full docs bundle — /llms-full.txt

For agents that want the API surface inline (so they don't need to fetch every page), we also publish a single flattened markdown bundle of the reference docs at https://www.pixldocs.com/llms-full.txt. This is the recommended source for an agent that will be generating code against our API.

Using PixlDocs from ChatGPT / Claude

The best route is the MCP server below — add it as a connector and the agent gets real tools. Failing that, any assistant that can fetch URLs can drive PixlDocs:

• Feed it /llms-full.txt as system context.
• Give it an API key as a stored secret in your own environment — never paste it into a public chat.
• Ask it to POST to /v1/render. The full request shape is at POST /v1/render.

MCP server

PixlDocs ships an official Model Context Protocol server, so Claude, ChatGPT, Cursor and any other MCP client can call PixlDocs as first-class tools — no glue code and no browser automation pretending to be an API. It is a hosted Streamable HTTP endpoint, so there is nothing to install.

• Endpoint: https://api.pixldocs.com/mcp
• Auth: OAuth 2.1 — paste the URL, approve in your browser, done. A client that cannot do OAuth sends Authorization: Bearer pxd_… with any workspace API key instead. One key type on every plan; renders are never watermarked.
• Stateless: every call is self-contained via template_id.

Connect it

Claude (claude.ai, paid plans) — Settings → Connectors → Add custom connector, paste the URL, click Connect. A PixlDocs page opens in your browser; approve it and the tools appear. There is no key to paste — the connector dialog has no field for one.

Claude Code — one line, then authenticate from inside the session:

claude mcp add --transport http pixldocs https://api.pixldocs.com/mcp
# inside Claude Code:  /mcp  →  pixldocs  →  Authenticate

Cursor — .cursor/mcp.json. Omit the header and Cursor runs the same browser approval.

{
  "mcpServers": {
    "pixldocs": {
      "url": "https://api.pixldocs.com/mcp",
      "headers": { "Authorization": "Bearer pxd_YOUR_KEY" }
    }
  }
}

VS Code — .vscode/mcp.json; VS Code completes the OAuth step itself.

{ "servers": { "pixldocs": { "type": "http", "url": "https://api.pixldocs.com/mcp" } } }

ChatGPT — Settings → Connectors → Create (developer mode), paste the URL, choose OAuth. n8n — the MCP Client Tool node with the URL above, transport HTTP Streamable, and a Bearer credential holding your key.

Anything that only speaks stdio — bridge it:

npx mcp-remote https://api.pixldocs.com/mcp --header "Authorization: Bearer pxd_YOUR_KEY"

Fill an existing document

• list_templates — enumerate the documents in the workspace.
• get_html_template / list_fields — read the markup and the exact keys it accepts.
• render_html_template — render it to PDF or PNG. At scale ≤ 1.5 an image comes back inline so the model can see the result, alongside the render metadata.

Author a new document

An agent does not have to write markup blind. It can describe the document in a sentence, or paste one it already has, and get back a real template with a declared field contract that has already rendered once.

• generate_html_template — one prompt (“a freight invoice with line items and GST”) → HTML, CSS, @field contract and sample data.
• import_html_template — paste an existing document; the fields are inferred and declared for you.
• create_html_template / update_html_template — write or amend the markup directly.
• render_html_template — render and look at it before handing it to the user.

Ship it

• integrate_html_template — turns a finished template into a working curl / Node / Python call against POST /v1/render, with this template’s real accepted keys already in the body, plus the /integrate link where you copy an API key. Pass publish: true to ship the template at the same time.

The default tool profile is html. It is deliberately small, so no client truncates it. …/mcp?profile=full restores the entire canvas surface if you need it, and …/mcp?profile=core is the older preferred set. The server echoes the active profile in the x-pixldocs-mcp-profile response header, and GET /mcp/tools lists the tools registered for a profile.

Writing an agent that renders PixlDocs

1. Discover templates

Over MCP, call list_templates. Without it, an agent needs a template UUID from the user. Templates are stable — a UUID never changes.

2. Read the field contract

Every template declares the keys it accepts. Over MCP that is list_fields; over HTTP it is GET /v1/templates/:id/fields. Produce a data object using exactly those keys — an unrecognised key is refused with 400 unknown_fields rather than dropped, so guessing fails loudly instead of shipping a wrong document.

3. Render

const res = await fetch("https://api.pixldocs.com/v1/render", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PIXLDOCS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template_id: "9f7b8380-710e-433a-a4c9-4ecafc986d35",
    format: "pdf",
    data: { /* fields matching the schema */ },
  }),
});
const pdf = Buffer.from(await res.arrayBuffer());

Guidelines for agent authors

• Never call the API from the browser. Keys are workspace-scoped and billable.
• Handle 202. Sync POST /v1/render falls back to async after 90s. Poll GET /v1/renders/:id.
• Respect the rate limit — 60 req/min on paid plans, 20 on Free, set by the account rather than the key. Pace off the RateLimit-* headers, and for bulk work batch via /v1/renders/batch.
• Retry only 429/500/502 with exponential backoff. See Errors.