MCP contracts LLM connectors Strict schemas

Pixelixe MCP documentation

This page is the technical MCP reference for connector behavior. It is intentionally stricter than the generic REST docs because it describes the exact chat-facing tool contracts, common LLM mistakes, and output rendering rules used by the Pixelixe MCP server.

Use this page for: ChatGPT apps, Claude connectors, n8n, Make, MCP servers, and agent workflows.

Use /docs/v2 for: the main human REST/API reference.

Setup guide
REST API docs
Tools Outputs Common mistakes Get tool docs Search documents Get document Graphic variant Create graphic
Pixelixe MCP workflow

Available MCP tools


Exact tool surface exposed by the remote Pixelixe MCP server.



pixelixe_get_tool_docs

Returns the MCP docs URL, REST docs URL, schema notes, strict contract summary, examples, and output rules for another Pixelixe tool.

pixelixe_search_documents

Lists or filters saved documents. This is the main discovery tool before selecting a document to reuse in template automation.

pixelixe_get_document

Convenience wrapper over Search Documents for a single document_uid, with optional inline preview image.

pixelixe_generate_graphic_variant

Maps to templateEngine. It edits an existing saved template and reuses its layout. It is not a free-form layout API.

pixelixe_create_graphic_from_json

Maps to createGraphicFromAPI. It creates a brand new editable layout from a strict JSON document.



Authentication

The MCP server expects Authorization: Bearer .... Depending on the client, this can be a direct Pixelixe API key or an MCP OAuth access token.

Contract policy

The historical Cloud Functions accept some legacy aliases. The MCP layer is intentionally stricter and documents the canonical field names the assistant should send.

Studio safety

This reference does not assume any Studio deep-link. MCP outputs focus on assets, URLs, and inline previews without modifying Studio routing.


How Pixelixe MCP should present output

The JSON payload is preserved, but the assistant should explain results in product language and show visuals when the server already provides them.



Case Expected assistant behavior
Search results Summarize the list in plain language. Mention name, format (width x height), document_uid, preview URL, HTML URL, and available modification names. Do not inline every preview image in a list.
Single document If a preview image exists, the MCP server may attach it inline as an image content block. The assistant should still explain what the document is and include the URLs.
Graphic variant, binary image response Display the image directly to the user. If the response is JSON instead, show the returned image or HTML URLs and summarize what was generated.
Create graphic with save_document=false Render or show the returned HTML directly. Do not claim the document was saved, and do not invent a document_uid.
Create graphic with save_document=true Show the generated image, provide the returned html_url, and mention the saved document_uid. If the server can fetch the image safely, it may also attach it inline.
Inline image fallback If inline image fetch fails, times out, or exceeds the size limit, the tool still succeeds. The assistant should fall back to the returned URLs.

Common LLM mistakes


The MCP layer is intentionally stricter than the historical runtime so these mistakes fail early and clearly.



Coordinates

Use top and left only for JSON to Graphic. Never use x and y. Never send layout coordinates at all to pixelixe_generate_graphic_variant.

Background handling

Do not use root key background. Use background_color, background_gradient, or background_image. Do not put a background item inside modifications.

Exact key naming

Use exact snake_case or hyphenated keys such as image_url, font-size, font-family, background-color, and text-align. Do not invent camelCase aliases.

Mixing the two generation modes

Use pixelixe_create_graphic_from_json to create a new layout. Use pixelixe_generate_graphic_variant only when you already have a saved template and want to target existing elements.

Wrong background-image placement

In JSON to Graphic, use root background_image. In template automation, target the existing template element named background-image with image_url.

Wrong output handling

If save_document=false, show the returned HTML. If save_document=true or a JSON variant response returns URLs, show the asset and links instead of dumping raw JSON.


pixelixe_get_tool_docs


Use this first when the assistant is unsure about the exact MCP contract for a generation tool. It is a documentation helper, not a business action.

{
  "tool_name": "pixelixe_create_graphic_from_json"
}

Returned fields include: docs_url, rest_docs_url, when_to_use, when_not_to_use, required_inputs, example_arguments, schema_notes, strict_contract, and output_handling.

Recommended use: call this before pixelixe_generate_graphic_variant or pixelixe_create_graphic_from_json when the user request is ambiguous.

pixelixe_search_documents


Discovery and filtering for saved documents and reusable templates.



Example

{
  "created_by": "owner",
  "width": 1080,
  "height": 1080
}

Related REST docs: Search Documents API

Accepted filters

user_uidOptional exact user filter.
document_uidOptional exact document filter.
created_byowner or api-editor.
widthOptional pixel width.
heightOptional pixel height.
folder_pathOptional folder path.

Returned document fields: name, width, height, last_modification_date, public_png_url, public_html_url, available_modifications, document_uid, and folder_path.

Recommended assistant behavior: present the list in plain language and use the returned document_uid for the next call to pixelixe_get_document or pixelixe_generate_graphic_variant.


pixelixe_get_document

Single-document retrieval built on top of Search Documents with document_uid.



{
  "document_uid": "32f59312815640e186cf17fe3fd5c1d9"
}

Behavior

  • Returns one normalized document payload or a not-found result.
  • Keeps the original preview and HTML URLs in structured content.
  • If public_png_url exists and the fetch is safe, the server may attach a true MCP inline image block.

pixelixe_generate_graphic_variant


Strict MCP wrapper around templateEngine.



Canonical example

{
  "document_uid": "32f59312815640e186cf17fe3fd5c1d9",
  "format": "json",
  "modifications": [
    {
      "element_name": "headline",
      "type": "text",
      "text": "Summer Sale"
    },
    {
      "element_name": "background-image",
      "type": "image",
      "image_url": "https://example.com/hero.jpg",
      "width": "cover",
      "height": "cover"
    }
  ]
}

Related REST docs: Image Automation API

Accepted root keys

document_uid
template_name
template_url
format
image_type
custom_field
uid
document_uid_verified
csv_uid
modifications

Required: one of document_uid, template_name, or template_url.


Accepted modification keys

name
element_name
type
text
image_url
color
background-color
border-color
border-size
font-size
font-family
text-align
width
height
visible
shape

Type requirements

textelement_name + text
imageelement_name + image_url
iconelement_name
shapeelement_name

Special values: format = image, json, base64, pdf, html. image_type = png or jpeg. width/height may use cover, auto, original, or a CSS-like pixel/string value.


Important runtime rules from templateEngine:

Do not use top, left, x, or y. The template already defines layout. Use element_name to target existing elements; name is only a compatibility fallback. Use background-color to recolor an existing element, or target the special existing element background-image with image_url. If background-color targets the background, the runtime removes the background image.

Forbidden MCP patterns: background_color, background_gradient, background_image, camelCase aliases, and layout coordinates.

Output behavior: if the upstream response is binary image, show it directly. If it is JSON, show image_url or html_url and any attached inline image. If it is HTML, render or display the HTML.


pixelixe_create_graphic_from_json

Strict MCP wrapper around createGraphicFromAPI and buildPixelixeHtmlFromJson.



{
  "document_name": "launch_post",
  "save_document": true,
  "width": 1080,
  "height": 1080,
  "background_color": "#f5f7fb",
  "modifications": [
    {
      "name": "headline",
      "type": "text",
      "text": "New Sneaker Drop",
      "top": 80,
      "left": 60,
      "font-size": 72,
      "color": "#111111"
    },
    {
      "name": "hero-image",
      "type": "image",
      "image_url": "https://example.com/sneaker.png",
      "top": 240,
      "left": 120,
      "width": 840,
      "height": 600,
      "object-fit": "cover"
    }
  ]
}

Required root keys

width
height
modifications

When save_document=true: document_name becomes required and must be alphanumeric with _ or - only.

Related REST docs: JSON to Graphic API


Preferred root keys

document_name
save_document
width
height
background_color
background_gradient
background_filter
background_image
font_family
custom_font_faces
modifications

Compatibility aliases and metadata

background-gradient
background-filter
background-image
bgimgwidth
bgimgheight
bgimgleft
bgimgtop
origbgimgwidth
origbgimgheight
origimgwidth
origimgheight
data-keyword
data_keyword

Accepted modification keys

name
element_name
type
text
image_url
color
background-color
border-color
border-size
border
border-style
border-radius
box-shadow
filter
font-size
font-family
font-weight
font-style
text-transform
text-decoration
text-shadow
text-stroke-width
text-stroke-color
line-height
letter-spacing
word-spacing
text-indent
transform
opacity
cursor
text-rendering
text-align
background-gradient
object-fit
object-position
width
height
top
left
z-index
visible
shape
icon

Type requirements

textname + type + text + top + left
imagename + type + image_url + top + left
shapename + type + top + left
iconname + type + icon + top + left

Important MCP restrictions

  • Use top and left. Never use x or y.
  • Do not use root key background.
  • Do not send type=background or a modification named background-image. Use root background_image instead.
  • Use canonical keys such as background_color, image_url, font-size, object-fit, and z-index.
  • Element names must be unique inside modifications.

Runtime behavior from buildPixelixeHtmlFromJson:

The renderer reads root background values from background_color, background_gradient, background_filter, and background_image. It supports custom font loading via custom_font_faces. For elements, it renders text, image, icon, and shape. The historical runtime knows a background type internally, but the MCP contract intentionally rejects it and redirects you to root background fields.

Output behavior: when save_document=false, the endpoint returns HTML and the assistant should render or show that HTML directly. When save_document=true, the endpoint returns JSON with document_uid, image_url, and html_url; the assistant should show the generated asset and provide the links.

Need screen-by-screen connector setup?


This MCP reference is the technical annex for connector behavior and strict schemas. For end-user setup steps in ChatGPT, Claude, n8n, Make, or Zapier, use the Help Center guide below.

Open MCP setup guide