Tools reference

All 15 MCP tools the Brand Stack connector exposes, with inputs, outputs, and example agent prompts.

The Brand Stack MCP server exposes 15 tools: 11 read tools, 2 image intake tools, and 2 generation tools. Tools are filtered by your token’s scopes, so read-only tokens see only the read tools.

The definitions come from the same tool registry (@brandstack/tools-engine) that powers the workspace CLI commands, so npx @brandstack/cli list-brands and the MCP list_brands tool are the same server code with the same inputs, rules, and error messages. Only the transport differs. Authenticate the CLI with an API key; MCP connectors use OAuth. Both hit POST /api/mcp, where scopes, credits, and rate limits are enforced once, server-side, for every caller.

Read tools (mcp:read)

list_brands

List every brand profile in the connected workspace. Returns id, name, source, personality keywords, and palette size. No inputs.

“Show me all my brands.”

get_brand

Fetch a single brand profile. The format parameter controls output:

Inputs: brand_id (UUID, required), format (optional).

“Get my Acme brand as a Tailwind config.”

list_products

List every product in the workspace, with name, industry, target audience, and lifecycle stage. No inputs.

get_product

Fetch a single product. Inputs: product_id (required).

list_personas_for_product

List every persona linked to a product. Returns compact summaries; use get_persona for the full record. Inputs: product_id (required).

“Who are the personas for my Operator product?”

get_persona

Fetch a single persona: demographics, goals, pain points, the generated long-form profile as Markdown (profileMarkdown), absolute image URLs (profileImageUrl, environmentImageUrl, safe to fetch or embed directly), and the id of the first linked product. Inputs: persona_id (required).

list_projects

List every project (a collection of related documents), with id, name, emoji, and timestamps. No inputs.

list_documents

List documents, paginated. Inputs:

• limit (1 to 100, default 50)
• offset (default 0)

Returns { documents, total, limit, offset }.

get_document

Fetch a single document. The body comes back as Markdown (contentMarkdown); documents authored before the editor moved to Markdown are converted on read. Inputs: document_id (required).

“Read me the latest Q4 strategy doc.”

list_assets

Search the workspace’s image library with optional filters:

Returns { assets, nextCursor }. Use nextCursor as the next call’s cursor to paginate. Screenshots that arrive through capture_screenshot, the CLI upload, or an upload link all land here with source_type: "upload".

“Find all the mockup-generated images for the Acme product.”

list_templates

List the workspace’s saved setups: reusable compositions (device, camera, atmosphere, aspect ratio) captured from a previous mockup. Completed setups only, newest first. Each entry carries the id you pass to create_mockup as template_id, plus title, deviceType, cameraPosition, cameraLens, atmosphere, aspectRatio, outputUrl, and tags.

Ids are UUIDs on rows you saved, so this is the only way to discover one. title is nullable; describe an untitled setup by its device and lighting.

Inputs: limit (default 50, max 100), search (matches the title).

“What saved mockup setups do I have?”

get_credits

Return the workspace’s remaining credits, split between subscription plan and one-time packs. No inputs.

This is also where a newly connected workspace’s welcome lands: the first call from a workspace that has never used the connector grants credits sized to 10 free mockups, and the response carries a welcome note saying so.

Image intake (mcp:write, no credits)

The generation tools take reference images as public https URLs the server fetches. These two tools, plus the CLI upload, are how an image gets one. None of them cost credits.

capture_screenshot

Capture a screenshot of a public web page on Brand Stack’s own servers and store it in the workspace library. This is the no-shell path: paste a URL in Claude’s chat or Cowork and the agent has a hosted screenshot in one call.

Inputs:

• url (required): public http(s) address. A local dev server (localhost, private networks) is not reachable from Brand Stack’s servers; capture those with Playwright, then upload the file through create_upload_link (or the CLI, if a key is configured).
• viewport (optional): desktop (1440×900, for MacBook and Studio Display mockups, the default) or mobile (390×844 at 2x, for iPhone mockups).
• full_page (optional, default false): capture the whole scrollable page. Keep it false for device mockups; a device screen shows one viewport.

Returns { url, width, height, assetId, deviceHint }. Pass url to create_mockup as screenshot_url. Takes 5 to 15 seconds.

“Capture mysite.com at a mobile viewport and make it an iPhone mockup.”

create_upload_link

Mint a 30-minute upload channel into the workspace, no login and no API key on either of its two routes:

• uploadUrl: a browser page where a person drops an image. The pasted-image path for clients with no shell: the user pasted a screenshot into the chat, the agent cannot move the bytes itself, so it sends the user this link and picks the upload back up from list_assets (source_type: "upload", newest first).

• uploadEndpoint: accepts the raw file bytes by POST, for agents that do have a shell but no CLI key:

  curl -X POST -H "content-type: image/png" -H "x-filename: shot.png" \
    --data-binary @shot.png "$UPLOAD_ENDPOINT"

  The response carries the hosted url (pass it as screenshot_url) plus width and height, which is what device inference runs on. No user step at all.

No inputs. Returns { uploadUrl, uploadEndpoint, validForMinutes, expiresAt }.

Uploading from a shell with the CLI

With an API key configured (npx @brandstack/cli login once, or BRANDSTACK_API_KEY), the CLI does the shell route in one command:

npx @brandstack/cli upload ./shot.png

prints the hosted URL plus the image’s width×height. Every --*-url flag on the CLI’s create-mockup also accepts a local path directly and uploads it first. Optional: an agent without a key uses create_upload_link and loses nothing but the shortcut. See Screenshots → mockups for the full flow.

Generation tools (mcp:write, consume credits)

Both tools consume credits from the connected workspace (a new workspace’s first 10 mockups are free). Generation typically takes 20 to 60 seconds and the call returns synchronously with the final image URL.

create_mockup

Generate a product mockup: a device, photographed in a real environment, with your screenshot on its screen. At least one of persona_id, template_id, device_type, screenshot_url, atmosphere, camera_position, or custom_instructions must be provided.

The tool’s description teaches the agent to infer before asking. The screenshot’s own dimensions answer the device question (portrait means iPhone with no question; landscape earns exactly one, MacBook Pro or Apple Studio Display), the coding session answers the persona question (the agent matches the product it is working on against list_products), and everything else has a sensible default. You get at most one short question, and none if you say “just make it”.

Most-used inputs:

• screenshot_url: the image shown on the device screen. Without it the screen content is invented.
• persona_id: pulls the persona’s demographics and reference imagery automatically.
• template_id: a saved setup’s UUID from list_templates. Applies that setup’s composition and uses its rendered image as the reference, the same as picking it in the studio.
• device_type / device_label: for example macbook_pro, iphone, studio_display.
• camera_position / camera_lens: for example Over the shoulder plus 35mm Wide.
• atmosphere: Natural Light, Studio Lighting, Golden Hour, Moody / Dark, Bright & Minimal, Neon / Vibrant, Outdoor Daylight. Free-form values are accepted.
• custom_instructions: free-form prompt. Takes precedence over the single-device default, so ask here for extra monitors or devices in shot.
• character_reference_url, style_reference_url, previous_output_url: further reference images.
• aspect_ratio: 16:9 (default), 3:2, 4:3, 1:1, 3:4, 2:3, 9:16.
• image_size: 0.5K, 1K (default), 2K, 4K. Higher tiers cost more credits.

Returns { mockupId, outputUrl, promptText }.

“Turn that screenshot into a MacBook Pro mockup with Natural Light.”

create_scene

Generate a lifestyle scene featuring a persona. persona_id is required. Either pass an environment_type preset or a free-form environment_prompt.

Inputs:

• persona_id (required): the subject of the scene.
• environment_type / environment_label: preset slug plus label.
• environment_prompt: free-form description; overrides the preset.
• camera_position / camera_lens, atmosphere, custom_instructions: same as mockup.
• character_reference_url, style_reference_url, previous_output_url.
• aspect_ratio, image_size: same as mockup.

Returns { sceneId, outputUrl, promptText }.

“Create a scene of persona <id> in a coffee shop, golden hour lighting, 9 aspect.”

A typical agent loop

1. capture_screenshot url="https://mysite.com" viewport="desktop"
   → { url, width: 1440, height: 900, deviceHint: "landscape ..." }
2. create_mockup screenshot_url="..." device_type="macbook_pro"
   → { mockupId, outputUrl, promptText }
3. list_assets source_type="mockup_generated" limit=5
   → confirms the new shot appears in the library