Docs MCP
MCP tools reference
The name, the description and the arguments of each tool of the Snapsbrew MCP server.
The Snapsbrew MCP server has 27 tools. This page lists them in the order that tools/list returns them.
A script makes this page from the tool classes in app/Mcp/Tools. Each description is the text that the server sends to the agent.
The hint columns show the MCP tool annotations. A client can use them to ask a person before a call. A dash means that the tool does not set the hint.
Read the MCP overview for the workflow and the error format.
Summary
| Tool | Title | Read only | Destructive |
|---|---|---|---|
whoami |
Who am I | Yes | No |
list-templates |
List templates | Yes | No |
get-template-details |
Get template details | Yes | No |
get-editor-document |
Get a template editor document | Yes | No |
describe-editor-document |
Describe the v2 editor document | Yes | No |
list-variant-properties |
List variant properties | Yes | No |
preview-template |
Preview a template | Yes | No |
preview-snap |
Preview a snap | Yes | No |
preview-design |
Preview an inline design | Yes | No |
create-snap |
Create a snap | No | Yes |
create-snap-from-design |
Create a snap from an inline design | No | Yes |
create-snaps-batch |
Create many snaps in one batch | No | Yes |
get-snaps-batch |
Read a snap batch | Yes | No |
cancel-snaps-batch |
Cancel a running snap batch | No | Yes |
describe-layers |
Describe layer structure | Yes | No |
design-guide |
Template design guide | Yes | No |
platform-guide |
Platform image rules | Yes | No |
image-purpose-guide |
Image purpose guide | Yes | No |
list-template-sizes |
List canvas size presets | Yes | No |
create-template |
Create a template | No | No |
edit-template |
Edit a template (any account in your company) | No | Yes |
publish-template |
Publish a template (any account in your company) | No | Yes |
put-editor-document |
Replace a template editor document (any account in your company) | No | Yes |
apply-editor-operations |
Apply validated editor layer operations | No | Yes |
preflight-editor-document |
Inspect a draft editor document before publishing | Yes | No |
export-creative-package |
Export a creative package | No | Yes |
get-creative-package |
Read a creative package | Yes | No |
whoami
Who am I
Returns the authenticated account (name, email, company). Call this first to confirm that the token works.
This tool takes no arguments.
list-templates
List templates
Lists the templates in your account. Each result includes the template id (UUID), title, dimensions, and its modifiable layers. Use the id with get-template-details, preview-snap, or create-snap.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
limit |
integer | No | Maximum number of templates to return (1–100, default 25). |
get-template-details
Get template details
Returns a single template with its layer keys and the modifications each layer accepts. Call this before building variants for preview-snap or create-snap — the layer keys it returns are exactly what you pass as "layer" in variants.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | UUID of the template (from list-templates). |
get-editor-document
Get a template editor document
Returns the v2 editor document and its revision. Pass that revision unchanged to put-editor-document. The document is scoped to your company.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | Template UUID. |
describe-editor-document
Describe the v2 editor document
Returns the versioned v2 editor-document contract, including apply-editor-operations grammar, limits, conflict recovery, and deferred capabilities. Read it before any editor-document mutation.
This tool takes no arguments.
list-variant-properties
List variant properties
Returns the full catalog of properties you can apply to a template layer in
variants, each with its value type, which layer types it applies to, and a concrete example. Use this to learn the override vocabulary before building variants for preview-snap or create-snap. Combine with get-template-details, which tells you the layer keys available on a specific template.
This tool takes no arguments.
preview-template
Preview a template
Renders a watermarked preview of a template as a self-contained HTML document so the human can see it before the final render. Optionally apply variants. Returns the rendered HTML plus the exact variants used. Use this to iterate, then call create-snap with the same variants to produce the final un-watermarked snap.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | UUID of the template to preview. | |
variants |
array of object | No | Per-layer overrides. Each item is an object with a "layer" key (a layer key from get-template-details) plus exactly one of: "text" (string), "image_url" (public https URL), "background_color" (#hex), "qr_content" (string), or "hidden" (true to drop the layer). Example: [{"layer":"headline","text":"Hello"},{"layer":"logo","image_url":"https://cdn.example.com/logo.png"}] | |
variants[].layer |
string | Yes | Layer key to override. | |
variants[].text |
string | No | Replacement text for a text layer. | |
variants[].image_url |
string | No | Public image URL for an image layer. | |
variants[].background_color |
string | No | Background color as #hex. | |
variants[].qr_content |
string | No | Content for a QR-code layer. | |
variants[].hidden |
boolean | No | Set true to hide the layer. |
preview-snap
Preview a snap
Renders a watermarked preview of the snap you intend to create — a template plus your variants — as a self-contained HTML document. Returns the rendered HTML and echoes the exact variants used. When the preview looks right, call create-snap with the SAME template_id and variants to get the final, un-watermarked snap.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | UUID of the template to render the snap from. | |
variants |
array of object | No | Per-layer overrides. Each item is an object with a "layer" key (a layer key from get-template-details) plus exactly one of: "text" (string), "image_url" (public https URL), "background_color" (#hex), "qr_content" (string), or "hidden" (true to drop the layer). Example: [{"layer":"headline","text":"Hello"},{"layer":"logo","image_url":"https://cdn.example.com/logo.png"}] | |
variants[].layer |
string | Yes | Layer key to override. | |
variants[].text |
string | No | Replacement text for a text layer. | |
variants[].image_url |
string | No | Public image URL for an image layer. | |
variants[].background_color |
string | No | Background color as #hex. | |
variants[].qr_content |
string | No | Content for a QR-code layer. | |
variants[].hidden |
boolean | No | Set true to hide the layer. |
preview-design
Preview an inline design
Renders a watermarked preview of a design you describe inline: a canvas (
sizepreset, orwidthandheight) plus alayersdefinition, with NO template. Nothing is saved. Returns the rendered HTML plus the exact canvas and layers it rendered. Iterate here, then pass the SAME canvas and layers to create-snap-from-design for the final un-watermarked image. Call describe-layers for the layer vocabulary and design-guide for how to compose it. If the human will reuse this design, call create-template instead so it has a saved template.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
size |
string | No | Canvas size preset, for example "instagram_story" or "open_graph". Sets width and height for you. Call list-template-sizes for every preset. | |
width |
integer | No | Canvas width in px (1–4000). Required only when you pass no size. |
|
height |
integer | No | Canvas height in px (1–4000). Required only when you pass no size. |
|
layers |
array | No | Layer definitions (array of layer objects), the same shape create-template takes. Each layer is { "key": " |
create-snap
Create a snap
Renders the FINAL, un-watermarked snap from a template and variants. Only call this after the human has approved a preview (preview-snap). Pass the same template_id and variants you previewed. Returns the snap id and the image URL. Idempotency keys are shared across every snap-creation tool.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | UUID of the template to render. | |
type |
string | No | image, pdf |
Output type. Defaults to image. |
format |
string | No | png, jpeg, webp |
Image output format (image type only). Defaults to png. Transparency requires png or webp. |
transparent |
boolean | No | Render on a transparent background (png/webp only). Defaults to false. | |
idempotency_key |
string | No | Optional. Send the same key when you retry after a timeout. The retry returns the same snap and does not render it again. Keys are honored for 24 hours, are scoped to your account, and accept letters, digits, underscores and hyphens, up to 191 characters. | |
variants |
array of object | No | Per-layer overrides. Each item is an object with a "layer" key (a layer key from get-template-details) plus exactly one of: "text" (string), "image_url" (public https URL), "background_color" (#hex), "qr_content" (string), or "hidden" (true to drop the layer). Example: [{"layer":"headline","text":"Hello"},{"layer":"logo","image_url":"https://cdn.example.com/logo.png"}] | |
variants[].layer |
string | Yes | Layer key to override. | |
variants[].text |
string | No | Replacement text for a text layer. | |
variants[].image_url |
string | No | Public image URL for an image layer. | |
variants[].background_color |
string | No | Background color as #hex. | |
variants[].qr_content |
string | No | Content for a QR-code layer. | |
variants[].hidden |
boolean | No | Set true to hide the layer. |
create-snap-from-design
Create a snap from an inline design
Renders the FINAL, un-watermarked snap from a design you describe inline: a canvas (
sizepreset, orwidthandheight) plus alayersdefinition, with NO template. No template is saved. Only call this after the human has approved a preview-design result, and pass the SAME canvas and layers you previewed. Returns the snap id and the image URL; template_id is null. Idempotency keys are shared across every snap-creation tool. If the human will reuse this design, call create-template instead.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
size |
string | No | Canvas size preset, for example "instagram_story" or "open_graph". Sets width and height for you. Call list-template-sizes for every preset. | |
width |
integer | No | Canvas width in px (1–4000). Required only when you pass no size. |
|
height |
integer | No | Canvas height in px (1–4000). Required only when you pass no size. |
|
layers |
array | No | Layer definitions (array of layer objects), the same shape create-template takes. Pass the exact array preview-design echoed back. Call describe-layers first for the property vocabulary and an example. | |
type |
string | No | image, pdf |
Output type. Defaults to image. |
format |
string | No | png, jpeg, webp |
Image output format (image type only). Defaults to png. Transparency requires png or webp. |
transparent |
boolean | No | Render on a transparent background (png/webp only). Defaults to false. | |
idempotency_key |
string | No | Optional. Send the same key when you retry after a timeout. The retry returns the same snap and does not render it again. Keys are honored for 24 hours, are scoped to your account and shared across every snap-creation tool, and accept letters, digits, underscores and hyphens, up to 191 characters. |
create-snaps-batch
Create many snaps in one batch
Renders up to 100 FINAL, un-watermarked snaps from ONE template and one set of variants per item. Returns a batch id right away and renders in the background. Only call this after the human has approved a preview (preview-snap). Poll get-snaps-batch with the batch id to read progress and collect the image URLs.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | UUID of the template every item renders from. | |
items |
array of object | Yes | One entry per snap, at most 100. Each entry carries its own "variants" and an optional "identifier" you use to recognize it in the result. | |
items[].identifier |
string | No | Your own name for this item. Defaults to item_1, item_2, and so on. | |
items[].variants |
array of object | No | Per-layer overrides. Each item is an object with a "layer" key (a layer key from get-template-details) plus exactly one of: "text" (string), "image_url" (public https URL), "background_color" (#hex), "qr_content" (string), or "hidden" (true to drop the layer). Example: [{"layer":"headline","text":"Hello"},{"layer":"logo","image_url":"https://cdn.example.com/logo.png"}] | |
items[].variants[].layer |
string | Yes | Layer key to override. | |
items[].variants[].text |
string | No | Replacement text for a text layer. | |
items[].variants[].image_url |
string | No | Public image URL for an image layer. | |
items[].variants[].background_color |
string | No | Background color as #hex. | |
items[].variants[].qr_content |
string | No | Content for a QR-code layer. | |
items[].variants[].hidden |
boolean | No | Set true to hide the layer. | |
title |
string | No | A name for this batch, shown in the account. Defaults to "MCP batch". | |
webhook_url |
string | No | Optional public https URL. ONE request is posted to it when the batch finishes. The address must be public: a private, loopback or link-local host is rejected. | |
type |
string | No | image, pdf |
Output type for every item. Defaults to image. |
format |
string | No | png, jpeg, webp |
Image output format for every item. Defaults to png. Transparency requires png or webp. |
transparent |
boolean | No | Render every item on a transparent background (png/webp only). Defaults to false. | |
idempotency_key |
string | No | Optional. Send the same key when you retry after a timeout. The retry returns the same batch and starts no second one. Keys are honored for 24 hours, are scoped to your account, and accept letters, digits, underscores and hyphens, up to 191 characters. |
get-snaps-batch
Read a snap batch
Reads the progress of a batch started by create-snaps-batch. Renders nothing. Returns the counts and every item with its status and image URL. Poll this about every 5 seconds. Stop when status is completed, failed or canceled.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
batch_id |
string | Yes | The batch id returned by create-snaps-batch. |
cancel-snaps-batch
Cancel a running snap batch
Stops a batch started by create-snaps-batch. Items that already rendered stay. Items that had not started are marked canceled and never render. An item that is rendering right now can still finish. This cannot be undone: a canceled batch cannot be resumed. A batch that already finished is left alone.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
batch_id |
string | Yes | The batch id returned by create-snaps-batch. |
describe-layers
Describe layer structure
Returns the structure of a template layer: the layer object shape (key, type, properties), the full property-name vocabulary, the value shape for each property, and a worked example. Call this BEFORE create-template or edit-template so the
layersyou pass are valid. This is the design-time vocabulary (how a layer is built); use list-variant-properties for the run-time override vocabulary.
This tool takes no arguments.
design-guide
Template design guide
Returns opinionated design guidance for building good-looking templates with the Snapsbrew layer vocabulary: canvas-size presets, a back-to-front layer-order convention, typography/color rules, composition recipes (promo, quote, event, product, coupon), anti-patterns, and a preflight checklist. Read this BEFORE create-template to plan the design; pair it with describe-layers, which gives the exact property names and value shapes.
This tool takes no arguments.
platform-guide
Platform image rules
Call this FIRST whenever the human names a platform — "an image for Instagram", "a post for LinkedIn", "an X card", "a TikTok". Returns what that platform does to an image after upload and the design rules that follow: which size preset to start from and why, how the platform crops the image, the DIRECTIONAL UI safe zones where the platform paints its own controls over the frame (Story, Reel, TikTok, Shorts, banners), accepted file formats and size limits, the export width and colour profile, plus platform-specific rules and anti-patterns. Covers Instagram, Facebook, X, LinkedIn, Threads, Pinterest, TikTok, YouTube, Snapchat, WhatsApp, web and email, display ads, and print. Accepts the names people actually type ("insta", "twitter", "og").
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
platform |
string | No | The platform the image is for. Accepts a key (instagram, facebook, x, linkedin, threads, pinterest, tiktok, youtube, snapchat, whatsapp, web, ads, print) or a common alias ("insta", "ig", "twitter", "fb", "og", "email", "shorts"), and a phrase like "instagram story". Leave it out to list every platform with its default size. |
image-purpose-guide
Image purpose guide
Call this whenever the human says what the image is FOR rather than where it goes — "an og:image / meta tag image", "a carousel", "a gallery", "a photo for the feed", "a profile picture", "a banner", "a YouTube thumbnail", "a product photo", "an email header", "a blog hero", "an ad". Returns the job that kind of image has to do, the size presets that fit it, the rules and failure modes specific to it, a layer recipe in the Snapsbrew vocabulary, an anti-pattern list and a preflight checklist. The
link_previewpurpose also returns the exact og: and twitter: meta tags to put in the page head. Pair it with platform-guide: this tool says what the image must achieve, platform-guide says what the platform will do to it.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
purpose |
string | No | What the image is for. Accepts a key (link_preview, feed_post, carousel, story, profile_picture, cover, video_thumbnail, ad, product_shot, email_header, article_header, presentation_slide) or a common alias ("og image", "meta tag", "gallery", "slides", "avatar", "banner", "thumbnail", "product photo", "newsletter"). Leave it out to list every purpose. |
list-template-sizes
List canvas size presets
Lists every canvas size preset you can pass as
sizeto create-template and edit-template — Instagram, Facebook, X, LinkedIn, Threads, Pinterest, TikTok, YouTube, Snapchat, WhatsApp, web and email, display ads, and print. Each preset gives its width, height, aspect ratio, and the safe margin to keep content away from the edges. Call it before create-template so you can name a preset instead of guessing pixel dimensions.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
platform |
string | No | Optional filter, for example "instagram", "youtube" or "print". Matches the platform name and the preset name. Leave it out to get every preset. |
create-template
Create a template
Creates a new template in your account from a title, a canvas size, and a layers definition. Give the canvas EITHER a
sizepreset (for example "instagram_story" — call list-template-sizes for the catalog) OR an explicitwidthandheight. Templates are the reusable designs that snaps are rendered from. Returns the new template id (UUID). A preview image is generated automatically.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
title |
string | Yes | Template title. | |
size |
string | No | Canvas size preset, for example "instagram_story", "youtube_thumbnail" or "open_graph". Sets width and height for you, so you can leave them out. Call list-template-sizes for every preset with its dimensions. | |
width |
integer | No | Canvas width in px (1–4000). Required only when you pass no size. |
|
height |
integer | No | Canvas height in px (1–4000). Required only when you pass no size. |
|
layers |
array | No | Layer definitions (array of layer objects). Pass [] for an empty canvas. Each layer is { "key": " |
edit-template
Edit a template (any account in your company)
Updates an existing template in your company (title, canvas size, and/or layers) by writing its DRAFT. Resize it with a
sizepreset (for example "instagram_story") or with an explicitwidthandheight. New snaps and previews keep rendering the last published version until you call publish-template — so an edit alone does not change what create-snap produces. Only do this when explicitly asked. Returns the updated fields. Any account in your company that can change templates can edit it.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | UUID of the template to edit. | |
title |
string | No | New title. | |
size |
string | No | New canvas size preset, for example "instagram_story". Sets width and height for you and overrides them if you pass both. Call list-template-sizes for every preset with its dimensions. | |
width |
integer | No | New canvas width in px (1–4000). Ignored when you pass a size. |
|
height |
integer | No | New canvas height in px (1–4000). Ignored when you pass a size. |
|
layers |
array | No | Replacement layer definitions (array of layer objects). REPLACES all existing layers. Each layer is { "key": " |
publish-template
Publish a template (any account in your company)
Publishes the current draft of a template in your company as a new immutable version. New snaps and previews render the PUBLISHED version, not the draft —
edit-templateonly changes the draft, so call this to make those edits take effect for create-snap and the preview tools. Returns the new published version number. Any account in your company that can change templates can publish it.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | UUID of the template whose draft you want to publish. |
put-editor-document
Replace a template editor document (any account in your company)
Atomically replaces a v2 editor document when revision matches. On editor_document_conflict, retain your draft and choose to reload, copy it, or cancel; never overwrite the returned current document automatically.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | Template UUID. | |
revision |
integer | Yes | Revision returned by get-editor-document. | |
document |
object | Yes | Full replacement v2 document. |
apply-editor-operations
Apply validated editor layer operations
Atomically applies a closed list of validated v2 layer property/type operations when revision matches. Reread the document after editor_document_conflict; never retry it by overwriting the returned document.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | Template UUID. | |
revision |
integer | Yes | Revision returned by get-editor-document. | |
operations |
array | Yes | One or more {operation, layer_key, property?, value?, type?} operations. operation is set_layer_property or set_layer_type. |
preflight-editor-document
Inspect a draft editor document before publishing
Checks known render invariants in the current v2 draft without mutating it. Returns structured issues; an empty issues list is not a visual-quality guarantee.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
template_id |
string | Yes | Template UUID. |
export-creative-package
Export a creative package
Renders up to 10 FINAL images from published template versions into one portable package. Returns a package id right away and renders in the background. Every item needs a template_id, a published template_version, a label and alt_text. Poll get-creative-package with the package id to read progress and collect the signed file URLs. A retry with the same idempotency_key returns the same package and starts no second one.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
idempotency_key |
string | Yes | Required. Send the same key when you retry. The retry returns the same package and starts no second one. Letters, digits, underscores and hyphens, at most 100 characters. | |
items |
array of object | Yes | Ordered list of 1 to 10 creatives. The response keeps this order. | |
items[].client_creative_id |
string | Yes | Your own stable id for this creative. Unique within the request. | |
items[].client_family_id |
string | No | Optional. Groups creatives that belong together. | |
items[].template_id |
string | Yes | UUID of a template in your account. | |
items[].template_version |
integer | Yes | A published version number of that template. Read it with get-template-details. | |
items[].label |
string | Yes | Display label for this creative. | |
items[].placement_key |
string | No | Optional provider-neutral placement, for example instagram.feed.organic. | |
items[].caption |
string | No | Optional caption to carry with the image. | |
items[].alt_text |
string | Yes | Required alternative text for the image. | |
items[].metadata |
object | No | Optional JSON object of your own fields. At most 16384 bytes and 6 levels deep. | |
items[].format |
string | Yes | png, jpeg, webp |
Image output format. |
get-creative-package
Read a creative package
Reads the progress of a package started by export-creative-package. Renders nothing. Returns the status, the counts, every item with its state, and the manifest with signed file URLs once output exists. Every call signs fresh URLs. Poll about every 30 seconds while status is building.
| Argument | Type | Required | Values | Description |
|---|---|---|---|---|
package_id |
string | Yes | The 36-character package id that export-creative-package returned. |