---
title: Tools reference
description: 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/api-keys); 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:

| Format | What it returns |
|--------|----------------|
| `json` (default) | Structured fields: colors, typography, voice, messaging, visual direction. |
| `markdown` | A printable style-guide doc. |
| `css` | CSS custom properties (`--brand-primary`, `--brand-text`, and so on). |
| `tailwind` | A Tailwind config snippet that extends your `theme.colors`. |
| `context` | A prompt-ready summary you can paste into a system prompt. |

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:

| Input | What it does |
|-------|--------------|
| `asset_type` | `image`, `logo`, or `avatar` |
| `source_type` | `mockup_generated`, `scene_generated`, `persona_profile`, `persona_environment`, `brand_logo_generated`, `brand_logo_external`, `attachment`, `upload` |
| `product_name` | Filter by product (exact match) |
| `search` | Substring search across `source_name` and `filename` |
| `cursor` | Pass the previous page's last `createdAt` for pagination |
| `limit` | 1 to 100, default 40 |

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:

  ```bash
  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](/mcp/api-keys) configured (`npx @brandstack/cli login` once, or `BRANDSTACK_API_KEY`), the CLI does the shell route in one command:

```bash
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](/mcp/screenshots) 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:16 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
```