MozaikaConnect your agent

The two values

Every MCP client needs the same two things from Mozaika. Everything further down is those two values written in each client's own file format.

Endpoint (remote, Streamable HTTP)
https://mozaika.design/mcp

Auth header
Authorization: Bearer YOUR_KEY_FROM_mozaika.design/connect

In Claude Code that is one command:

claude mcp add --transport http mozaika https://mozaika.design/mcp \
  --header "Authorization: Bearer YOUR_KEY_FROM_mozaika.design/connect"

There is no npm package to install, no local process to run and no OAuth flow. A key is free, needs no card, and is issued at https://mozaika.design/connect.

What you need

Endpoint
https://mozaika.design/mcp
Transport
Streamable HTTP. It is a remote server, so clients that speak remote MCP natively need no install, no Node and no local process.
Auth
One header: Authorization: Bearer YOUR_KEY_FROM_mozaika.design/connect. The scheme is matched case-insensitively, Token is accepted as an alternative scheme, and a bare key sent with no scheme at all is accepted too.
OAuth
Not supported and not needed. The server publishes no OAuth discovery endpoints and reads the key from the authorization header only.
Key shape
mzk_ followed by 32 URL-safe characters. If the value in your config does not look like that, it is not a key.
Where the key comes from
Free, no card, at https://mozaika.design/connect.
Free tier
Unlimited search across the whole library, plus 25 metered tool calls a month. Full decodes are limited to a rotating monthly open shelf of 30 products.
Paid
From the price on the pricing page at https://mozaika.design/pricing. Flat pricing, no credits.

Step 1: get a key

Open https://mozaika.design/connect and sign in with Google, with GitHub, or with a one-time code sent to your email. There is no password and no card. The account is created and the MCP key is shown on the same page, immediately.

Every account gets a real key, including free ones. Free does not mean a trial that expires; it means a smaller monthly budget of metered calls. Search is not metered at all.

Step 2: add the server to your client

Replace YOUR_KEY_FROM_mozaika.design/connect with the key from step 1 in every snippet below. If you paste a snippet without replacing it, the client will report a successful connection and then fail every real call. See troubleshooting.

Claude Code (CLI)

Run this in your project directory, then restart Claude Code.

claude mcp add --transport http mozaika https://mozaika.design/mcp \
  --header "Authorization: Bearer YOUR_KEY_FROM_mozaika.design/connect"

Confirm it registered with claude mcp list. To change the key later, run claude mcp remove mozaika and add it again.

Cursor

Add to ~/.cursor/mcp.json, or to a project-local .cursor/mcp.json.

{
  "mcpServers": {
    "mozaika": {
      "url": "https://mozaika.design/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY_FROM_mozaika.design/connect" }
    }
  }
}

Codex

Add to ~/.codex/config.toml, then start a new Codex session. The key is http_headers, which takes literal header values, so the token goes in directly.

[mcp_servers.mozaika]
url = "https://mozaika.design/mcp"
http_headers = { "Authorization" = "Bearer YOUR_KEY_FROM_mozaika.design/connect" }

VS Code

Add to .vscode/mcp.json in the workspace, or to your user config via Command Palette and "MCP: Open User Configuration". Note the top-level key is servers, not mcpServers, and type must be present.

{
  "servers": {
    "mozaika": {
      "type": "http",
      "url": "https://mozaika.design/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY_FROM_mozaika.design/connect" }
    }
  }
}

Windsurf

Settings, then MCP, then Add; or edit ~/.codeium/windsurf/mcp_config.json. Note the key is serverUrl, not url.

{
  "mcpServers": {
    "mozaika": {
      "serverUrl": "https://mozaika.design/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY_FROM_mozaika.design/connect" }
    }
  }
}

OpenCode

Add to opencode.json in the project, or to ~/.config/opencode/opencode.json. Two differences will silently break a copied Cursor config here: the top-level key is mcp, not mcpServers, and type must be remote.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mozaika": {
      "type": "remote",
      "url": "https://mozaika.design/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer YOUR_KEY_FROM_mozaika.design/connect" }
    }
  }
}

Claude Desktop

Settings, then Developer, then Edit Config, which opens claude_desktop_config.json. Restart Claude Desktop afterwards. This route bridges the remote server through mcp-remote, so it needs Node.js on the machine.

{
  "mcpServers": {
    "mozaika": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://mozaika.design/mcp",
        "--header", "Authorization: Bearer YOUR_KEY_FROM_mozaika.design/connect"
      ]
    }
  }
}

Why the bridge rather than pasting the URL as a custom connector: Anthropic's remote-MCP connector documentation marks request-header authentication as a beta being rolled out gradually, and Mozaika has no OAuth fallback to take its place. Without that beta a URL-only connector arrives here with no Authorization header at all, and an anonymous handshake succeeds on this server by design, so the connector shows as connected and lists every tool before the first real call returns 401. If your connector settings do offer a custom header, type the value with the word Bearer included, because the value is sent exactly as entered.

Raycast

Search "Manage MCP Servers", then Install Server, then Transport: HTTP, and enter these two values.

Transport   HTTP (Streamable)
URL         https://mozaika.design/mcp
Header      Authorization: Bearer YOUR_KEY_FROM_mozaika.design/connect

Any other MCP client

Kilo Code, Kiro, Amazon Q, Antigravity and anything else that speaks Streamable HTTP need exactly two values.

Endpoint (Streamable HTTP)
https://mozaika.design/mcp

Auth header
Authorization: Bearer YOUR_KEY_FROM_mozaika.design/connect

If your client accepts only a command rather than a URL, wrap it with mcp-remote exactly as in the Claude Desktop block above.

Step 3: verify the key actually authenticates

Do not trust the word "connected" in your client. Verify with a real tool call. This one uses get_web_benchmark, which is free and unmetered, so the check costs nothing from your monthly budget.

curl -sS https://mozaika.design/mcp \
  -H "Authorization: Bearer YOUR_KEY_FROM_mozaika.design/connect" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_web_benchmark","arguments":{}}}'

The server runs stateless, so that single POST is enough: no separate initialize round trip and no session id are required. A working key returns a server-sent event stream beginning event: message, followed by a JSON-RPC result. A missing or wrong key returns HTTP 401 with a JSON body whose error field is invalid_token and whose error_description names the specific cause.

Inside the agent, do the same in two steps. Ask it to call get_web_benchmark, which proves the key authenticates without spending a metered call. Then ask it to call search_screens for something you expect to exist, and get_design_system on a slug the search returned. A real answer contains hex values, font weights and a spacing scale. If that product is outside this month's free shelf you get a structured result instead, carrying gated: true and the list of products that are free right now; that is a working key too, not a failure.

What one call returns

Mozaika decodes real shipped products from the live DOM, so the payload is measured values rather than adjectives. get_design_system(site) returns colors under named roles (background, text, primary, secondary, accent, link, button_bg, button_text) with every hex normalized, fonts and font roles, the type scale, the spacing scale, primary and secondary button specs, framework and personality. Deep-decoded products add measured button hover and focus states, a shadow elevation scale, motion durations and easings, the brand's own CSS custom properties under css_vars, and icon DNA (style, grid, stroke weight, corner).

The same system comes out in the format your codebase wants. Pass format as design_md, tailwind, css, tokens or astryx to get just that text, or all to get every one of them alongside the raw token dict.

The library behind those calls is 588 products decoded into 548 measured design systems, 1,768 full-page screens and 3,873 sliced sections, so a section-level question is answered with that section's own numbers.

What the free tier includes

When a call is gated, the result is structured data rather than an error. It carries gated: true, a reason of either off_shelf or quota, a free_open_shelf array naming every product that is free this month, free_calls_remaining_this_month, and an upgrade object with the prices and the pricing URL. An agent can read that and pick a product from the shelf instead of stalling. For an off-shelf get_design_system the result also carries a preview with the colour roles, fonts and personality, plus a withheld array naming the build-layer fields a paid seat adds, so nothing is dropped silently.

Which of the 23 tools are metered

Metering splits the tools by what they do, not by how often you call them. Ten tools never touch the monthly budget; thirteen cost one call each.

Free and unmetered

Metered on the free tier, 1 call each

Ten plus thirteen is the whole toolset. On the free tier the three comparison tools (compare_sections, compare_components, compare_recipes) also draw their comparison panel from that month's shelf. Paid plans remove both limits: no monthly call budget and no open shelf, so full decodes work across the whole library.

Make the agent use it without being asked

Connecting the server does not change the agent's habits. Add one rule to AGENTS.md, CLAUDE.md, or .cursor/rules so it reaches for a measured spec instead of its own average.

## Design

When building or restyling UI, pull the target design system with the Mozaika
MCP (get_design_system) and build to those exact color roles, type scale,
spacing steps and radii. Use get_section for the specific section you are
building. Do not invent tokens.

Troubleshooting

The client says connected, but every tool call fails

This failure looks like a broken server and is not one, and it is not a syntax problem in your config file either. An MCP handshake does not authenticate. The handshake and capability-listing methods are deliberately allowed without a key, so a client with no Authorization header, or with the placeholder still in it, completes the handshake and displays all 23 tools. The first tools/call then returns 401.

The methods an anonymous caller may use are exactly initialize, notifications/initialized, ping, tools/list, prompts/list, prompts/get, resources/list and resources/templates/list. They exist so directory health checks and inspectors can see the server, and they expose no library data. Everything else needs a key. If your client lists the tools but nothing works, assume the header is missing or unreplaced rather than that the server is down.

401 invalid_token

The response body distinguishes five causes in its error_description. Read it rather than guessing.

Two things are not the cause, so do not spend time on them. A lowercase bearer is accepted, and so is the bare key with no scheme in front of it. If one of those is the only thing unusual about your config, the key itself is the problem.

Where the key lives, and rotation

Your current key is always at https://mozaika.design/connect while signed in, and the page has a regenerate control. Regenerating invalidates the previous key immediately, so every client config holding the old one has to be updated. If one machine started failing without you changing anything there, check whether the key was regenerated elsewhere; the 401 body names the rotation date when it can.

HTTP 406 Not Acceptable

The exact error is Not Acceptable: Client must accept both application/json and text/event-stream. Streamable HTTP replies as an event stream. Send Accept: application/json, text/event-stream, and send Content-Type: application/json with it. Real MCP clients do this for you; this one shows up when calling the endpoint by hand with curl or from a script.

You have used all 25 free calls

The tool result says so plainly, reports free_calls_remaining_this_month as zero with reason set to quota, and states that the calls reset on the 1st. Search still works and is still unmetered, and so are the other nine free tools listed above. To continue immediately, see https://mozaika.design/pricing.

The product you asked for is not on the open shelf

On the free tier a full decode is limited to that month's 30-product shelf, and the gated result comes back with reason set to off_shelf and the shelf listed by name in free_open_shelf. Domain spellings resolve first, so asking for stripe.com is not treated as a different product from Stripe. For an off-shelf product get_design_system still returns the colour roles, fonts and personality, so the agent has a usable reference and can either switch to a shelf product or continue with what it has.

Claude Desktop asks for a command and npx is not found

The Claude Desktop route runs npx -y mcp-remote, which requires Node.js on the machine. Install Node, or use a client that speaks remote MCP directly, such as Claude Code, Cursor, Codex or VS Code.

Keep the key out of git

Two of the config files above are project-local by default: .cursor/mcp.json and .vscode/mcp.json. Both live inside the repository, so a key pasted into one is committed unless you exclude it. Either put the config in the user-level file instead (~/.cursor/mcp.json, or the VS Code user configuration) or add the project file to .gitignore. If a key has already been pushed, regenerate it at https://mozaika.design/connect; the old one stops working immediately.

Other ways to use the same library

See also: pricing, browse the library, The Measured Web.

More: every decoded design system, The Measured Web (how the web is actually designed, measured), The Drift Ledger (what changed last night).