Skip to content

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 (size preset, or width and height) plus a layers definition, 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": "", "type"?: "", "properties": [ { "name", "value" } ] }. Pass [] or omit for a blank canvas. Call describe-layers first for the property vocabulary and an example.

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 (size preset, or width and height) plus a layers definition, 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 layers you 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_preview purpose 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 size to 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 size preset (for example "instagram_story" — call list-template-sizes for the catalog) OR an explicit width and height. 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": "", "type"?: "", "properties": [ { "name", "value" } ] }. Call describe-layers first for the full shape, property vocabulary, and an example.

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 size preset (for example "instagram_story") or with an explicit width and height. 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": "", "type"?: "", "properties": [ { "name", "value" } ] }. Call describe-layers first for the full shape, property vocabulary, and an example.

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-template only 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.

Edit this page on GitHub