Brand MCP reference

Start with the Brand MCP quickstart to connect and authenticate. This reference covers the details when you need them. Agents obtain current app requirements directly from commerce_describe, tool schemas and commerce://guide; reading this page is optional.

Choose an app

Call commerce_describe without arguments to discover your authorized apps. Then call it with an app_key to read the current fields, required inputs, allowed choices, person photos and output pack. Availability does not guarantee a generation will succeed.

App	Preparation tool	Full output pack
Fashion Catalogue (`fashion_catalog`)	`commerce_prepare_catalog`	Cropped Image (image); Front (image); Back (image); Side (image); Full Body (image); Catalog video (video)
Catalogue Photos and Video (`catalog_upgrade`)	`commerce_prepare_catalog_upgrade`	Front view (image); Side View (image); Close-up (image); Video (video)
Product Ad Banners (`product_banners`)	`commerce_prepare_banners`	Ad 1 (image, 9:16); Ad 2 (image, 9:16); Ad 3 (image, 9:16); Video Ad 1 (video, 5 seconds); Video Ad 2 (video, 5 seconds); Video Ad 3 (video, 5 seconds)
Virtual Try-On (`virtual_try_on`)	`commerce_prepare_try_on`	Selfie Output (image, 9:16); Full body Output (image, 9:16); Video (video)
Apparel Ad Video (`apparel_ad_video`)	`commerce_prepare_apparel_video`	Ad video (video, 20 seconds)
Listing Images & URL to Product Ad (`non_apparel_ad_video`)	`commerce_prepare_product_video`	Ad Video (video, 10 seconds, 9:16)

Use optional output_ids from commerce_describe to select deliverables; omission prepares the full pack. Prerequisite generation is automatic and included in the estimate. Ask only the missing inputs returned by preparation, together. Reuse retained_inputs when supplying answers. Images-only skips downstream video work; video-only includes required images. Selection happens before generation, not just when displaying results. Internal AI models remain fixed. The full packs above are available choices, not a requirement to generate every output. Read commerce_describe for current output IDs, availability, allowed choices and person photos. Input requirements depend on the selected outputs; preparation returns the actual missing questions. A selected producer retains its authored number of files. Product inputs contain productName and an images array; omit unknown optional product facts. For person_reference, send either {source: "preset", preset_id: "ID from commerce_describe"} or {source: "upload", asset_url: "HTTPS image URL"}. Upload local files first. Do not copy example or saved sample photos into missing inputs.

Fashion Catalogue

Create a styled fashion shoot from front, back and side photos of the same garment. Choose a preset person or custom person photo, garment framing, location and day/night lighting. Full output pack: Cropped Image (image); Front (image); Back (image); Side (image); Full Body (image); Catalog video (video). Returns a prepared plan before generation; no Shopify connection to Lamina is required.

Input	Type	Requirement / default	Description
`front_image_url`	image	Required when needed by the selected outputs	Front view of the actual garment.
`back_image_url`	image	Required when needed by the selected outputs	Back view of the same garment.
`side_image_url`	image	Required when needed by the selected outputs	Side or three-quarter view. Required until the no-side-image path is verified.
`person_reference`	person_reference	Required when needed by the selected outputs	Use the supplied person photo, or a preset ID from commerce_describe. If the user delegates selection, choose a listed preset and show it in the review; otherwise ask.
`garment_type`	choice	Required when needed by the selected outputs	Upper Wear, Bottom Wear or Full Body.
`shoot_mode`	choice	Optional; default Day Shoot	Day or night lighting; defaults to Day Shoot.
`environment`	choice	Required when needed by the selected outputs	Choose a supported shoot location.
`instructions`	text	Optional; default blank	Optional additional creative instructions; defaults to blank.

Catalogue Photos and Video

Upgrade apparel listing media from a product name and photos. Choose a preset person or custom person photo; body description and location are optional. Full output pack: Front view (image); Side View (image); Close-up (image); Video (video). Returns a prepared plan before generation; no Shopify connection to Lamina is required.

Input	Type	Requirement / default	Description
`product`	product	Required when needed by the selected outputs	Product name and image URLs from the user or connector. These are the only required product properties. Omit unknown optional properties; never invent a vendor, description or price. No store connection required.
`person_reference`	person_reference	Required when needed by the selected outputs	Use the supplied person photo, or a preset ID from commerce_describe. If selection is delegated, choose a listed preset and show it in the review; never invent an ID.
`body_description`	text	Optional; default blank	Optional body styling description; blank leaves the model reference in control.
`environment`	choice	Optional; default System Detected	Supported location; System Detected lets the workflow select it.

Product Ad Banners

Create campaign banners and animated variants using product photos, your logo, brand styling, headline, CTA and audience. Subheading and offer are optional. Choose this for banner creatives; choose a film app for a story ad. Full output pack: Ad 1 (image, 9:16); Ad 2 (image, 9:16); Ad 3 (image, 9:16); Video Ad 1 (video, 5 seconds); Video Ad 2 (video, 5 seconds); Video Ad 3 (video, 5 seconds). Returns a prepared plan before generation; no Shopify connection to Lamina is required.

Input	Type	Requirement / default	Description
`product`	product	Required when needed by the selected outputs	Product name and image URLs from the user or connector. These are the only required product properties. Omit unknown optional properties; never invent a vendor, description or price. No store connection required.
`logo_image_url`	image	Required when needed by the selected outputs	Actual brand logo.
`brand_colors`	text	Required when needed by the selected outputs	Brand colors, supplied or explicitly delegated.
`brand_fonts`	text	Required when needed by the selected outputs	Brand fonts, supplied or explicitly delegated.
`tone`	text	Required when needed by the selected outputs	Tone of voice for the campaign.
`headline`	text	Required when needed by the selected outputs	Headline based on real product facts; agent proposals require review.
`cta`	text	Required when needed by the selected outputs	Call to action approved for this campaign.
`geography`	text	Required when needed by the selected outputs	Target market; never reuse the sample market.
`audience`	text	Required when needed by the selected outputs	Intended audience.
`subheading`	text	Optional; default blank	Optional subheading.
`offer`	text	Optional; default blank	Actual promotional offer, or blank for no offer. Do not invent discounts.

Virtual Try-On

Show an actual customer wearing apparel using their photo and product name/images. Use the customer photo; there is no preset-person choice. Full output pack: Selfie Output (image, 9:16); Full body Output (image, 9:16); Video (video). Returns a prepared plan before generation; no Shopify connection to Lamina is required.

Input	Type	Requirement / default	Description
`product`	product	Required when needed by the selected outputs	Product name and image URLs from the user or connector. These are the only required product properties. Omit unknown optional properties; never invent a vendor, description or price. No store connection required.
`selfie_image_url`	image	Required when needed by the selected outputs	The actual customer photo; no sample or preset substitute.

Apparel Ad Video

Create a clothing campaign film with music, logo and timed text overlays. Supply clothing product name/images, brand logo, target geography and audience. Full output pack: Ad video (video, 20 seconds). Returns a prepared plan before generation; no Shopify connection to Lamina is required.

Input	Type	Requirement / default	Description
`product`	product	Required when needed by the selected outputs	Product name and image URLs from the user or connector. These are the only required product properties. Omit unknown optional properties; never invent a vendor, description or price. No store connection required.
`logo_image_url`	image	Required when needed by the selected outputs	Actual brand logo.
`geography`	text	Required when needed by the selected outputs	Target geography.
`audience`	text	Required when needed by the selected outputs	Target audience.

Listing Images & URL to Product Ad

Create a product ad from a listing URL and ordered listing photos. The authored app requests four scenes, feature text and music, without voiceover. No logo is required. The URL is passed as text; webpage retrieval and product-fact accuracy are not verified. Full output pack: Ad Video (video, 10 seconds, 9:16). Returns a prepared plan before generation; no Shopify connection to Lamina is required.

Input	Type	Requirement / default	Description
`listing_url`	listing_url	Required when needed by the selected outputs	HTTPS product listing URL supplied by the user or connector. Passed as text to the authored workflow; page retrieval is not guaranteed.
`listing_images`	image URL array (1–8, ordered)	Required when needed by the selected outputs	One to eight actual product listing image URLs, in the desired reference order. Upload local files first. Unused image slots are cleared; sample photos are never reused.

Note: The authored app receives the listing URL as text; it does not have verified webpage retrieval. Review generated feature claims against the real product. Note: The authored video prompt mentions nine references. With fewer than eight listing photos, visual fidelity needs review; no sample photos are substituted. If the user asks for an “ad” without a format, ask whether they want banners with short animations or a campaign film. Otherwise choose from the stated purpose. The table lists each app’s full pack. With Brand MCP contract 1.3.0 or later, select existing deliverables using output_ids from commerce_describe.outputs[].id. Omitting output_ids keeps the full pack. This selection applies only to Brand MCP; other Lamina MCPs and general app APIs keep their existing behavior.

Select images, video or specific outputs

For “images only,” take the IDs whose type is image. For “video only,” take the requested video IDs. Pass those IDs to the app’s preparation tool alongside its inputs:

// description is the result of commerce_describe({ app_key: "catalog_upgrade" }).
const imageIds = description.outputs
  .filter((output) => output.type === 'image')
  .map((output) => output.id);
// Supply actual product/person inputs along with output_ids: imageIds
// to commerce_prepare_catalog_upgrade.

A selected video automatically generates its required images and other upstream steps. Their cost is included in the estimate; do not ask for separate prerequisite approval. An images-only selection skips downstream video work. Preparation returns a concise selection_summary, selected outputs, and only the missing inputs relevant to that selection. required_for_output_ids describes each field’s applicability; the existing required_for_run flag describes its base app requirement. Use preparation’s actual questions, returned together, rather than asking every base field again. Reuse retained_inputs, including output_ids, when supplying the missing answers. IDs select existing output producers, not arbitrary file counts or extra variations. A video-only app may have no selectable image deliverables even when it generates images internally. Empty, unknown or foreign-app IDs are rejected; never retry an invalid selection by omitting it and generating the full pack. A changed selection requires a new prepared plan and review. Final results show the selected deliverables; prerequisite work remains in execution records. preview_output_ids only selects thumbnails for an existing result and does not control generation. Use the live description for exact field names and supported choices. Submit known inputs to preparation even when incomplete; needs_input groups the remaining questions. Reuse supplied facts and ask only for missing required inputs. Never invent a product, logo, person, discount or price.

Product data and person photos

Product inputs require productName and one to ten image URLs. Other product facts are optional; a Shopify token, product ID and store domain are not required.

{
  "product": {
    "productName": "Blue linen shirt",
    "images": ["https://cdn.shopify.com/front.jpg", "https://cdn.shopify.com/back.jpg"]
  }
}

These example URLs are placeholders: use real accessible images on approved hosts. The first image is the default hero image unless heroImage is supplied. Catalogue apps accept either a preset person or a custom person photo:

{ "person_reference": { "source": "preset", "preset_id": "ID_FROM_COMMERCE_DESCRIBE" } }

{ "person_reference": { "source": "upload", "asset_url": "https://cdn.shopify.com/person.jpg" } }

commerce_describe returns all named person photos. MCP Apps hosts can show the full gallery; native image previews are limited to four per call. Pass app_key and preview_preset_ids to preview others. Use returned IDs, not guessed names. If the user delegates selection, choose a supported option and show the exact reference in the review. “Model selection” here means the photographed person. Internal AI models, prompts, providers, graph structure and generation settings are fixed, except for the inputs explicitly exposed by the app. Try-On uses selfie_image_url for the actual customer.

Upload multiple files

For each local file, call commerce_upload_asset with its name, MIME type, actual byte size and public_upload_accepted: true. For example:

{
  "filename": "front.jpg",
  "mime_type": "image/jpeg",
  "byte_size": 123456,
  "public_upload_accepted": true
}

Obtain the user’s acceptance of public visibility first. HTTP PUT the file bytes to the returned uploadUrl, using contentTypeHint as the Content-Type header. Only after the upload succeeds, pass assetUrl in the appropriate input field. Repeat for back/side images, logo and person reference; product images go in product.images. Uploads support PNG, JPEG and WebP, up to 20 MiB each, with additional decoded-image validation. They are public assets in shared configured storage. Private uploads are not supported, and operators may disable uploading. Existing accessible URLs on approved asset hosts can be used instead. The agent host needs file-reading and HTTP-upload capability: MCP cannot read chat attachments by itself.

Prepare, review, generate and retrieve

Read commerce_credits and describe the chosen app.
Call its preparation tool with actual inputs and optional output_ids. Resolve the grouped needs_input questions, retaining previously supplied inputs and selection.
When preparation returns awaiting_approval, show its review, included outputs, estimated credits, plan ID and settings. Obtain user authorization to generate.
Call commerce_execute with the exact returned planId, planFingerprint, a positive integer maxCredits covering the estimate, and a unique idempotencyKey.
Poll commerce_status with the returned runId at bounded intervals until terminal.
Present the returned media using the gallery/player or your host’s native preview. Keep the named original-file links and inspect the media before judging quality.

For example, inspect Try-On with commerce_describe({"app_key":"virtual_try_on"}), then prepare using the product object above plus selfie_image_url. Preparation does not start generation. Do not pass new inputs to execution; changed inputs require a new prepared plan and review. After an uncertain execution response, retry with the same key and unchanged arguments, or check the known run. Do not start another paid run blindly. commerce_cancel requests cancellation; submitted work may still incur credits. maxCredits checks the estimate, not a guaranteed provider-spend ceiling. Exact per-run settled credits can be unavailable (spent: null); do not treat a workspace balance change as the cost of one run. Output verification checks provenance and media structure, not creative quality. Do not substitute old canvas outputs for missing MCP results. Brand MCP does not publish to Shopify. An agent can publish returned media through its own Shopify connector when the user authorizes it.

Show photos and generated results

Brand MCP supplies three views: all person references, the exact selected/custom reference in the review, and the run’s actual output images/videos. The read-only viewer never generates media. Selecting a preset sends your agent a request to prepare the inputs for review. Video has playback controls and does not autoplay.

Agent host supports	Presentation
MCP Apps (`io.modelcontextprotocol/ui`)	Gallery, enlargement, video player and original-file actions
Native MCP image blocks	Labelled thumbnails plus links to every original image/video; use the host’s preview tool for video
Text only	Clearly labelled original-file links; explain that inline display is unavailable

The host decides what it can render. Advertising the UI resource does not prove a particular chat displayed it. Reload the MCP connection’s tool/resource discovery after an update; the endpoint, tool names and existing OAuth grants are unchanged.

Claude, Codex and other agent clients

Brand MCP is a remote HTTP MCP service, not a Codex-only integration. Each client must complete Lamina OAuth for the intended workspace and retain the same access checks. Connect Claude Code with:

claude mcp add --transport http lamina-brand https://app.uselamina.ai/mcp/commerce

Then use /mcp in Claude Code to authorize. For Claude app/Desktop, add the same URL as a custom remote connector and complete authorization.

Claude app/Desktop: supports interactive MCP Apps. The Brand gallery uses the standard bridge rather than requiring OpenAI-specific APIs. Connector enablement, organization policy and the host’s sandbox still determine rendering. See Claude’s interactive connector guide.
Claude Code/CLI: can call the same tools and consume native image results. An image reaching the model is not proof the terminal displays it to a human. Use the returned image files/links and a supported browser preview for video; do not promise an embedded terminal gallery. See Claude Code MCP setup and image results.
Codex and other agents: use the capabilities actually available in that host: MCP Apps, native media previews, or named original links. Do not branch solely on the agent’s name or infer UI support from a successful tool call.

The protocol and browser fixtures are tested; this is not a claim that every version of every client has been manually verified. Before a team rollout, authorize its actual client, display reference photos beyond the first four, and retrieve an owned completed run with images and video. This check requires no new paid generation. For agent authors:

Preserve content blocks of type image and resource_link. Printing only structuredContent or JSON drops the human-visible previews. Forward media with your host’s actual supported display API, not an invented helper.
Use presentation.items for labels, stable IDs and original URLs. A fifth image is still present when only four thumbnails are embedded. Call commerce_status with runId and up to four preview_output_ids from that run to preview remaining images.
inlinePreview distinguishes included, unavailable, not_requested and not_applicable. It describes the response, not whether the host displayed it.
Say “shown” only after producing a visible preview. Do not rely solely on remote image tables or download media to get around a host’s display restrictions.
Refresh the same run to retrieve outputs; never regenerate just to fix display. A failed or cancelled run can contain usable partial media and must retain its status.

The viewer refreshes active runs every 10 seconds, backs off on transient errors, stops on authorization errors or terminal status, and pauses after ten minutes. Manual refresh remains available. Broken/expired media shows a message and retains its original link; an unavailable thumbnail does not change the generation status.

How agents receive instructions

MCP initialization supplies server instructions.
tools/list supplies tool descriptions and JSON input schemas. Full access currently exposes 12 tools; grants and app readiness can reduce the list.
Read the commerce://guide MCP resource for the same runtime guide.
commerce_describe supplies current app-specific fields, choices and previews.

The server does not edit the agent’s system prompt or project files; the host controls how instructions are presented. The optional @uselamina/skill package adds written guidance, but installing it does not configure MCP or authorize a workspace. Use the live resource and schemas even when an installed skill is older. Install the optional guidance into a project with:

npx @uselamina/skill@latest

To refresh an existing installation, run npx @uselamina/skill@latest --update. Presentation guidance is included from version 0.1.14. Update older installations explicitly. Native skill clients receive the bundled Brand MCP reference; rule-only clients can read commerce://guide through MCP. This is separate from the connection setup in the Brand MCP quickstart.

Troubleshooting

Symptom	What to check
`authorization_required` in a browser	Connect through your MCP host and complete OAuth
`invalid_token` or wrong token audience	Reauthorize this Brand MCP connection; do not copy the main MCP token
`insufficient_scope`	Approve the required read/write scopes in your client
`commerce_forbidden`	Ask your workspace operator to check membership and Brand MCP grants
An app is missing or unavailable	Check `commerce_describe`; an operator may need to review its changed contract
Missing inputs or invalid choices	Use the returned questions and exact IDs/options from the live description
Upload issuance succeeds but preparation fails	Confirm the bytes were uploaded and the URL, type and size pass validation
Estimate exceeds budget	Review the estimate and choose a sufficient budget before execution
Run fails or returns no final outputs	Report its run ID and error; inspect the authored app before retrying
JSON arrives but photos are absent	Preserve native image blocks and resource links; do not print only structured data
No gallery/player appears	Check host MCP Apps support and reload tool/resource discovery; use native previews or named links
Image works in a tab but fails in the viewer	Inspect the host’s media policy and sandbox CSP; operators must allow the exact approved media origin
A photo or video no longer loads	Refresh status for the current URL; report inaccessible/expired media without starting another run

OAuth resource discovery is available at https://app.uselamina.ai/.well-known/oauth-protected-resource/mcp/commerce. Read and write scopes are lamina:creative:read and lamina:creative:write. See MCP OAuth Install for the shared authorization flow.

Current tested limits

The 15 October 2026 live sample returned full MCP output packs for apps 1–5. Visual caveats included animated logo distortion, oversized film logos and cropped full-body framing. The previous app 6 failed at its final caption overlay after caption text was truncated. It has now been replaced by the listing-video app above. The replacement has passed contract and preparation checks; a fresh paid generation is not yet verified. These sampled results are not a guarantee across all inputs. Check final status and review outputs before publishing.

Additional connection options

Client configuration

For clients using mcpServers configuration:

{
  "mcpServers": {
    "lamina-brand": {
      "url": "https://app.uselamina.ai/mcp/commerce"
    }
  }
}

Configuration formats vary by host. For a stdio-only client, use this alternative:

{
  "mcpServers": {
    "lamina-brand": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.uselamina.ai/mcp/commerce"]
    }
  }
}

The bridge completes OAuth in your browser. Do not add an API key or service-role key.

Overview

Install

Concepts

API Reference

Guides

Brand MCP reference

Choose an app

Fashion Catalogue

Catalogue Photos and Video

Product Ad Banners

Virtual Try-On

Apparel Ad Video

Listing Images & URL to Product Ad

Select images, video or specific outputs

Product data and person photos

Upload multiple files

Prepare, review, generate and retrieve

Show photos and generated results

Claude, Codex and other agent clients

How agents receive instructions

Troubleshooting

Current tested limits

Additional connection options

Client configuration

​Choose an app

​Fashion Catalogue

​Catalogue Photos and Video

​Product Ad Banners

​Virtual Try-On

​Apparel Ad Video

​Listing Images & URL to Product Ad

​Select images, video or specific outputs

​Product data and person photos

​Upload multiple files

​Prepare, review, generate and retrieve

​Show photos and generated results

​Claude, Codex and other agent clients

​How agents receive instructions

​Troubleshooting

​Current tested limits

​Additional connection options

​Client configuration

Choose an app

Fashion Catalogue

Catalogue Photos and Video

Product Ad Banners

Virtual Try-On

Apparel Ad Video

Listing Images & URL to Product Ad

Select images, video or specific outputs

Product data and person photos

Upload multiple files

Prepare, review, generate and retrieve

Show photos and generated results

Claude, Codex and other agent clients

How agents receive instructions

Troubleshooting

Current tested limits

Additional connection options

Client configuration