Tools
Use a template id exactly as
list_templates returns it.
Find a template
Ask for the templates and their layers:includeLayers, an entry holds only the id and the name. With it, each layer comes with the name to use in modifications:
suggestInput names the field to set: text for a text layer, src for an image layer, and null for every other type. A layer without a name shows as Untitled.
Layer names come from the template editor, where you rename a layer by double-clicking it. Modifications explains how a name matches a layer.
Pass layer values
modifications is an object keyed by layer name. A string sets the text of the layer, and an object sets the fields of that layer. The array format of the REST API is not valid here.
A full example for
create_image:
Read the result
create_image returns the image inline, with a line that gives its format and size in bytes. Your client decides how to show or save the image.
create_pdf stores the file and returns a link:
Compose an image without a template
Usecreate_image_from_shapes when no template fits. Give the tool a canvas and a list of shapes. It draws the shapes in order and returns the image, so the assistant can design a one-off banner or invoice.
The canvas object is optional. It is 1200 by 630 pixels and white unless you set these fields:
Every shape has
type, x, y, width, and height, in pixels from the top left of the canvas. The first shape is at the back and the last is on top. Three more fields work on every type: opacity (0 to 1), rotation (degrees, clockwise), and style.
A few rules:
icontakes an Iconoir name, for examplecheck-circleorarrow-right. A name that Iconoir does not have fails the call.srctakes an HTTPS URL or a data URL. A remote image loads with the same rules as in a template: PNG, JPEG, WebP, or SVG, and a failed download returnsFETCH_IMAGE_ERROR.- A table has one value per column in every row. This differs from
modifications, where a row is an object.variantisline,grid(default),minimal,striped,compact,bordered, orprimary-header. styletakes CSS property names in camelCase, for examplepadding,boxShadow,lineHeight, andletterSpacing. A key that the renderer does not support fails the call with anUnrecognized keymessage. Set the size withwidthandheight, not withstyle.- A field on the shape, such as
colororborderRadius, wins over the same key instyle. - A color is a hex value,
rgb(),hsl(), or a CSS color name.
A full example, an invoice:
Handle errors
A failed call returnsisError: true and a text message in one of two forms:
A missing or expired token gets HTTP 401 with the error
invalid_token before any tool runs, so a tool never returns UNAUTHORIZED. Your client then signs in again. RATE_LIMITED and TOO_MANY_REQUESTS do not occur, because the MCP server has no request rate limit. Handle errors lists the codes of the REST API.