# BrandSweets — agent integration guide

> The brand memory and iteration layer for AI agents. Extract a brand from a domain or shape one on a canvas, then serve it as structured, agent-readable data — brand.md, tokens.json, brand.css, and a per-brand MCP endpoint every future session already knows.

This file tells a coding agent (Claude Code, Cursor, or any MCP-capable client)
how to integrate BrandSweets: connect the MCP endpoint, install the skills, read
a brand as brand.md / tokens.json / brand.css, and keep every output on-brand.

## What BrandSweets is

BrandSweets is an agent-native brand platform. A brand is stored as a validated
BrandDoc — identity, voice, role-based design tokens (color, typography, spacing,
radius, gradients), a logo/asset inventory, and usage rules — and served as the
formats agents actually consume. There is no bespoke SDK: you read plain files
and/or call MCP tools.

## Read a brand (no auth, public brands)

Every public brand at `/b/<slug>` exposes three stable, machine-readable URLs:

- `https://brandsweets.com/b/<slug>/brand.md` — narrative brief to GROUND on before writing (text/markdown)
- `https://brandsweets.com/b/<slug>/tokens.json` — role-based W3C DTCG design tokens (application/json)
- `https://brandsweets.com/b/<slug>/brand.css` — CSS custom properties; `@import` and a prototype is on-brand (text/css)

Fetch `brand.md` first for voice, story, dos & don'ts and usage rules. Use
`tokens.json` / `brand.css` to map real colors and type onto your UI — never
invent a hex or a font.

## Connect over MCP

Two Streamable-HTTP endpoints:

| Endpoint | Access | Auth |
| --- | --- | --- |
| `https://mcp.brandsweets.com/{slug}/mcp` | One brand, read-only | none |
| `https://mcp.brandsweets.com/w/{workspace}/mcp` | Whole workspace, read + write | `Authorization: Bearer <workspace-api-key>` |

Public read (one brand), `.mcp.json`:

    {
      "mcpServers": {
        "brandsweets": { "type": "http", "url": "https://mcp.brandsweets.com/{slug}/mcp" }
      }
    }

Workspace loop (read + write — reads brands, creates brands, designs logos, runs
the creation loop; a write key auto-approves edits):

    {
      "mcpServers": {
        "brandsweets": {
          "type": "http",
          "url": "https://mcp.brandsweets.com/w/{workspace}/mcp",
          "headers": { "Authorization": "Bearer <workspace-api-token>" }
        }
      }
    }

Or, in Claude Code:

    claude mcp add --transport http brandsweets https://mcp.brandsweets.com/{slug}/mcp

Create a workspace API key in the app under **Settings → Workspace API keys**. A
`bsk_r_…` read key grounds read-only; a `bsk_w_…` write key additionally unlocks
brand edits, the creation and logo loops, and (Pro) imagery. Your workspace slug
is the `<workspace>` segment of the URL.

## Install the skills plugin

    claude plugin marketplace add ethanplusai/brandsweets
    claude plugin install brandsweets-skills

Then enter your workspace slug and API token when prompted. The bundle wires the
workspace MCP server plus five design skills:

- `brandsweets-on-brand` — fetch the brand system first, map tokens onto Tailwind/shadcn/CSS, use the real contrast pairs, screenshot-review against the brand.
- `brandsweets-brand-design` — run the creation loop; with a write key, create a brand from nothing and build it up.
- `brandsweets-logo-design` — start a logo round, submit original vector marks, run the render → QA → critique loop.
- `brandsweets-imagery` — on-brand image generation (Pro + your own provider key).
- `design-taste` — framework-agnostic frontend craft; works even before a brand exists.

## Keep output on-brand

1. GROUND before you generate: fetch `brand.md` (or call the MCP `brand://<slug>/system` resource) at the start of the session.
2. Use ONLY the brand's tokens — colors by role, the declared type families and weights, the real logo asset URLs. No invented values.
3. Respect usage rules (MUST / MUST NOT / SHOULD). Honor logo clearspace, min sizes and allowed backgrounds.
4. Match the voice — tone attributes, preferred/avoided vocabulary, sample copy register.
5. Review the render against the brand and correct drift before shipping.

## Discovery

- Machine-discoverable manifest: `https://brandsweets.com/.well-known/mcp.json`
- Orientation file: `https://brandsweets.com/llms.txt` (concise) and `https://brandsweets.com/llms-full.txt` (everything in one fetch)
- Human setup guide: `https://brandsweets.com/docs/agents`
- Brand directory: `https://brandsweets.com/b`

---

_BrandSweets · https://brandsweets.com · this guide is also served as HTML at /docs/agents._