01What is BrandCodex
BrandCodex is an open brand identity registry that stores brand guidelines in a structured, machine-readable format. It serves as the bridge between how humans design brands and how AI agents consume them.
Today, brand guidelines live in PDF decks, Figma files, and shared drives. Designers understand them. AI agents do not. When you ask an AI to "create a presentation using our brand," it has no reliable way to look up your colors, typography rules, or voice guidelines.
BrandCodex solves this by giving every registered brand a structured identity profile that both humans and machines can read. Each brand gets a public profile page, a set of machine-readable JSON files, and an MCP endpoint that AI tools like Claude, Cursor, and Windsurf can connect to directly.
The result: AI agents that genuinely understand your brand, not ones that guess based on a loose prompt. Every color token, every voice attribute, every usage rule is explicitly structured and accessible via a standard protocol.
02Traditional vs Machine-Readable Brand Guidelines
Traditional brand guidelines were designed for humans to interpret. They work well when a designer reads a PDF and applies their judgment. But they break down completely when software needs to use them programmatically.
📄 Traditional Guidelines
- Locked in PDFs and slide decks
- Colors described as "Brand Blue"
- Voice described in prose paragraphs
- Rules rely on human interpretation
- No API, no endpoint, no protocol
- Out of date the moment they're exported
⚡ Machine-Readable (MRBS)
- Structured JSON with semantic tokens
- Colors as hex + role + context rules
- Voice as explicit attribute arrays
- Rules as structured do/don't constraints
- MCP endpoint for real-time access
- Single source of truth, always current
Why does this matter?
Consider what happens when you tell Claude "write me an email in our brand voice." Without machine-readable guidelines, Claude guesses. It might produce something generically professional, but it won't capture the specific attributes that make your brand sound like your brand.
With MRBS, Claude can look up that your voice is "authoritative yet accessible, technical yet human", that you sound like "a knowledgeable colleague explaining clearly" and don't sound like "a marketing brochure full of buzzwords." The difference in output quality is dramatic.
The core insight: Brand identity isn't just for designers anymore. Every AI tool that generates text, images, code, or presentations on your behalf needs access to your brand rules. MRBS makes that access standardized and automatic.
03The MRBS Format
MRBS (Machine-Readable Brand System) is the file format used by BrandCodex. It organizes brand identity into a directory of JSON files, each covering a specific aspect of the brand.
your-brand/ ├── brand.manifest.json # Brand metadata + entry point ├── visual/ │ ├── colors.tokens.json # Color palette with semantic roles │ └── typography.tokens.json # Font families, scales, weights ├── identity/ │ ├── voice-tone.json # Voice attributes + examples │ └── brand-values.json # Core values with descriptions ├── rules/ │ └── constraints.json # Usage dos and don'ts ├── assets/ │ └── logos/ │ ├── manifest.json # Logo variants + contexts │ └── *.svg # Logo files └── _meta/ └── config.json # MRBS version + generation info
Color tokens example
Instead of saying "our primary color is Brand Purple," MRBS encodes the exact value, its semantic role, and where it should and shouldn't be used:
{
"color": {
"brand": {
"primary": {
"$value": "#2D1B69",
"name": "Codex Purple",
"semantic_role": "brand_identity",
"recommended_contexts": ["headers", "hero_backgrounds"],
"prohibited_contexts": ["error_states", "warning_text"]
}
}
}
}
This level of structure means an AI agent doesn't just know the color — it knows when to use it and when not to. The same principle applies across typography, voice, values, and rules.
Voice & tone example
{
"voice": {
"core_attributes": [
"Authoritative yet accessible",
"Technical yet human"
],
"sounds_like": [
"A knowledgeable colleague explaining clearly"
],
"doesnt_sound_like": [
"A marketing brochure full of buzzwords"
]
}
}
04How MCP Works
MCP (Model Context Protocol) is an open standard created by Anthropic that lets AI models connect to external data sources in real time. Think of it as a USB port for AI — instead of pasting information into a prompt, the AI can reach out and pull what it needs.
BrandCodex runs an MCP server for every registered brand. When you connect Claude (or any MCP-compatible tool) to your brand's endpoint, the AI gains live access to your full brand identity.
What happens when an AI connects
AI discovers available tools
The MCP server tells the AI what it can access: get_brand_identity, get_brand_colors, get_brand_voice, and check_color_compliance.
AI calls tools as needed
When you ask "write a social post in our brand voice," the AI calls get_brand_voice to retrieve your voice attributes before writing anything.
Structured data flows back
The server returns precise JSON — not a blob of text. The AI receives typed tokens with semantic roles, constraints, and usage rules.
AI applies brand rules to output
The AI uses the retrieved guidelines to shape its response: correct colors, right voice, proper typography, within stated constraints.
Connecting to a brand MCP server
Every brand registered in BrandCodex gets an MCP endpoint at:
# Per-brand endpoint https://www.brandcodex.org/brand/{slug}/mcp # Example: BrandCodex's own endpoint https://www.brandcodex.org/brand/brandcodex/mcp # Full registry endpoint (all brands) https://www.brandcodex.org/mcp
To connect in Claude Desktop, add the server to your claude_desktop_config.json:
{
"mcpServers": {
"brandcodex": {
"type": "url",
"url": "https://www.brandcodex.org/brand/brandcodex/mcp"
}
}
}
Available MCP resources
Each brand server exposes these resources via the brand:// URI scheme:
05Getting Started
There are two ways to register your brand in BrandCodex:
Option A: Manual submission
Use the brand submission wizard to fill in your brand details through a step-by-step form. You'll define colors, upload logos, set voice attributes, and publish — BrandCodex generates the MRBS files automatically.
Register your namespace
Pick a unique slug (e.g. my-brand) and provide your brand name, tagline, and contact email.
Build your identity
Add colors (minimum 3), upload logos, define typography, voice attributes, values, and usage rules through the visual builder.
Publish
Hit publish to generate your MRBS files and activate your MCP endpoint. Your brand is now discoverable by any AI agent.
Option B: Git import
If you already maintain an MRBS toolbook repository (or want to manage your brand identity as code), use the Git import method. Point BrandCodex to a public Git repo containing a valid brand.manifest.json at the root.
Toolbook template: Fork the MRBS toolbook template on GitHub to get a ready-made directory structure with all the right file names and schemas.
06API & Endpoints
BrandCodex provides a REST API alongside the MCP server. The API returns JSON and requires no authentication for public brands.
# List all registered brands GET /api/v1/brands # Get a specific brand's full identity GET /api/v1/brands/{slug} # Get a specific component GET /brand/{slug}/colors GET /brand/{slug}/typography GET /brand/{slug}/voice GET /brand/{slug}/values GET /brand/{slug}/rules GET /brand/{slug}/logos
MCP endpoints
# Registry-wide (all brands) POST /mcp # Per-brand POST /brand/{slug}/mcp # JSON-RPC 2.0 methods supported: initialize resources/list resources/read tools/list tools/call ping
MCP tools available
When connected to a brand's MCP server, AI agents can call these tools:
When connected to the registry-wide endpoint (/mcp), agents can additionally call list_brands to discover all available brands, and get_brand_component to access any brand's specific section.