API Reference / MCP

Let your agent design and render.

PixelDrive ships a hosted Model Context Protocol server. Point Claude, Cursor, VS Code, or any MCP client at one URL and your assistant can browse templates, design them, and render branded images on demand — using the same templates and credits as the REST API.

Endpoint: https://pixeldrive.pro/mcp · transport: Streamable HTTP

Listed in the official MCP Registry as pro.pixeldrive/pixeldrive

Connect

First, create a token in API tokens. Then add the server with one command or click:

Claude Code — one command

claude mcp add --transport http pixeldrive https://pixeldrive.pro/mcp \
  --header "Authorization: Bearer pdrv_your_token"

Cursor & VS Code — one click

Installs the server, then swap the placeholder token for yours in the client’s MCP settings.

Add to Cursor Add to VS Code

Any MCP client — paste the config

{
  "mcpServers": {
    "pixeldrive": {
      "url": "https://pixeldrive.pro/mcp",
      "headers": { "Authorization": "Bearer pdrv_your_token" }
    }
  }
}

Claude Desktop — proxy the remote server over stdio

Claude Desktop talks stdio, so wrap the remote URL with mcp-remote:

{
  "mcpServers": {
    "pixeldrive": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://pixeldrive.pro/mcp",
        "--header", "Authorization: Bearer pdrv_your_token"
      ]
    }
  }
}

Authentication

The MCP server uses the same Bearer token as the REST API — one secret per account, created and revoked from API tokens. Send it as Authorization: Bearer pdrv_…. The token is hashed at rest; a missing or revoked one returns 401. Every render is attributed to your account and spends from your credit balance.

What your agent can do

26 tools — the full editor and renderer, callable by prompt. Your agent can go from “make me a launch graphic” to a finished PNG without you touching the editor.

Discover & inspect

describe_capabilities	What the editor + renderer support (element types, fit modes, limits)
list_templates	Your templates
get_template	A template’s full element tree
get_template_variables	The variables (payload keys) a template exposes
list_gallery_templates	Browse the starter gallery
list_fonts	Available fonts
list_renders	Your recent renders

Find assets

search_photos	Search stock photos
search_icons	Search the icon library
attach_image_from_url	Pull in any external image by URL

Design & edit templates

create_template	New blank template at a given size
duplicate_template	Clone an existing template
add_element	Add a text, image, SVG, or shape
add_elements	Add many elements in one call
update_element	Change any element’s properties
duplicate_element	Clone an element
reorder_element	Change z-index / stacking order
remove_element	Delete an element
update_page	Page size, background, settings
mark_as_variable	Expose an element as a render variable (payload key)

Lay out

align_elements	Align elements to the canvas
stack_elements	Stack in a row or column
place_relative	Position one element relative to another

Render

preview_image	Free, ephemeral render the model can see while iterating
generate_image	Final saved render — returns a permanent URL (1 credit)
generate_batch	Many final images at once (billed per image)

Credits

Only final renders cost credits. Everything an agent does while iterating is free:

preview_image	free	Ephemeral preview the model sees while iterating — never billed.
generate_image	1 credit	Final saved render. A cache hit (same template + payload) is free.
generate_batch	1 / image	Billed per generated image; cache hits in the batch are free.
everything else	free	Listing, designing, searching, marking variables — all free.

Out of credits returns 402. Top up on the billing page.

Capability introspection

Agents don’t have to guess. describe_capabilities returns a machine-readable manifest of what the editor and renderer support — element types, text auto-fit modes, the override fields, output format, and limits — so the model can plan a valid design before it builds. Pair it with get_template_variables to learn a specific template’s exact payload keys.

Example

Once connected, just ask:

List my PixelDrive templates, then generate an image from the
"product-launch" template with the headline "Spring Sale", the
price "$49", and the hero image from this URL: https://…/shoe.png

The agent calls list_templates → get_template_variables → preview_image (free, to check) → generate_image and hands you back a permanent PNG URL.

Troubleshooting

401 Unauthorized	Token	Missing/expired token. Create one in API tokens and put it in the Authorization header.
Tools don’t appear	Restart	Restart the client after editing config. Confirm the URL is exactly https://pixeldrive.pro/mcp.
Render didn’t save	Tool	preview_image is free + ephemeral; use generate_image for a permanent URL.
402 Payment Required	Credits	Out of credits — top up on the billing page.