---
title: Setup
description: Step-by-step instructions for connecting Brand Stack to Claude Code, Claude.ai web, Cursor, Codex, and any other MCP-compatible client.
---

The MCP endpoint URL is the same for every client:

```
https://www.brandstack.dev/api/mcp
```

The first connection from any client kicks off the OAuth handshake: your browser opens to a consent screen where you sign in (if you aren't already) and pick which workspace the client should access.

That handshake is the entire setup. There are no API keys to create, copy, or store: every tool, including screenshot capture, uploads, and generation, runs over the OAuth connection. (API keys exist separately, for people who want to script the [CLI](/mcp/api-keys) outside an AI client; you never need one to use the connector.)

You must be an **admin** of the workspace you authorize. Members will see the install instructions but can't grant access; ask an admin to connect on their behalf, or use a workspace you own.

## Claude Code

The Claude Code CLI ships with an `mcp` subcommand. Add Brand Stack with one line:

```bash
claude mcp add --transport http brandstack https://www.brandstack.dev/api/mcp
```

The first time you run a session in that directory, Claude opens your browser to the consent screen, you approve, and the connection is saved. Every subsequent session reuses the refresh token.

Verify it landed:

```bash
claude mcp list
```

You should see `brandstack` listed with `http` transport.

To remove the connection:

```bash
claude mcp remove brandstack
```

This deletes Claude's local copy of the tokens. To also revoke them server-side, visit **Settings → Developer → Authorized clients** in Brand Stack and revoke from there.

## Claude Desktop

Claude Desktop reads its MCP servers from `claude_desktop_config.json`. The
file path depends on your OS:

| OS | Path |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

You can find this from inside the app: **Settings → Developer → Edit Config**.

Add Brand Stack as an MCP server:

```json
{
  "mcpServers": {
    "brandstack": {
      "url": "https://www.brandstack.dev/api/mcp"
    }
  }
}
```

If you already have other MCP servers configured, merge the `brandstack` entry into your existing `mcpServers` map rather than replacing it.

Restart Claude. The first time you call a Brand Stack tool, your browser opens to the consent screen.

## Claude.ai web (Connectors)

1. Open [claude.ai](https://claude.ai) in your browser.
2. Click your avatar → **Settings** → **Connectors**.
3. Click **Add custom connector**.
4. Paste `https://www.brandstack.dev/api/mcp` as the server URL.
5. Click **Add**. Claude redirects you to the Brand Stack consent screen.
6. Sign in (if needed), pick a workspace, click **Allow**.

The connector now appears in your sidebar and is available in any conversation. To use it, mention it explicitly ("use the Brand Stack connector to list my personas") or let Claude pick it up from context.

## Cursor

Cursor reads from `~/.cursor/mcp.json` (or `.cursor/mcp.json` at the project root for a project-scoped config).

```json
{
  "mcpServers": {
    "brandstack": {
      "url": "https://www.brandstack.dev/api/mcp"
    }
  }
}
```

Restart Cursor after editing the file. The first time you call a Brand Stack tool from Cursor's chat, your browser opens to the consent screen.

## Codex (OpenAI)

Codex CLI uses `~/.codex/config.toml`:

```toml
[mcp_servers.brandstack]
url = "https://www.brandstack.dev/api/mcp"
```

After editing, run any Codex command and the OAuth flow opens automatically.

## Other MCP clients

Any client that supports the [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) and OAuth 2.1 (RFC 9728 protected-resource discovery) works out of the box. Point the client at `https://www.brandstack.dev/api/mcp` and let the OAuth dance happen.

If your client only supports older MCP transports (SSE-only, no OAuth), open an issue. We'll prioritize compatibility based on demand.

## Verifying the connection

Once connected, ask the AI: "List my Brand Stack brands." It should return a list of every brand profile in the connected workspace. If it doesn't, see [Troubleshooting](/mcp/troubleshooting).

## Your first mockup is the best test

A newly connected workspace's **first 10 mockups are free**; the credits
land on your balance the first time the connector touches the workspace,
and the agent will tell you so.

The fastest way to feel the whole flow:

```text
Take a screenshot of what we're building and turn it into a mockup with Brand Stack.
```

In a coding agent, that screenshots the app, uploads the file (no API
key needed: the agent mints an upload link and posts the file to it),
infers the device from the screenshot's shape, and asks you one question
at most. In Claude's chat or Cowork, paste a public URL instead and the
agent has Brand Stack capture the page itself. See
[Screenshots → mockups](/mcp/screenshots) for every variation, and
[Example prompts](/mcp/prompts) for more to try.

## Optional: an API key for the CLI

Everything above works with the connector alone. If you also want to run
workspace commands yourself from a terminal or CI (`brandstack
list-brands`, `brandstack create-mockup`), that path authenticates with
an [API key](/mcp/api-keys) instead of OAuth: mint one in Settings, then
Developer, and run `npx @brandstack/cli login` once. Entirely optional,
and nothing in the agent flows depends on it.