Feeding Design Tokens to AI via MCP

Ask Claude to build a profile card and it generates clean, working code—then you spend ten minutes replacing bg-blue-500, #3B82F6, and px-4 with the actual tokens from your design system. Every time. The AI isn't making mistakes; it genuinely has no idea what your design decisions are.

Model Context Protocol changes that. It gives AI tools a live connection to your design system so the first output uses your actual tokens, not training data defaults.

What MCP Does

Model Context Protocol is Anthropic's open standard for connecting AI assistants to external data sources. Instead of pasting your token list into every prompt, the AI queries your design system on demand through a local server.

The flow looks like this:

Claude Code ◄──── MCP ────► @framingui/mcp-server ◄──── tokens.json

When you ask the AI to build a component, it queries the MCP server, receives your token names and values, and generates code using those names from the start. No manual substitution after the fact.

The tokens are read on demand, so when you update tokens.json, the next AI generation automatically uses the new values. There's no re-pasting context into prompts and no stale token list to maintain.

Setting Up the MCP Server

The fastest path is the init command, which handles framework detection, package installation, and MCP configuration in one step:

npx -y @framingui/mcp-server@latest init

This writes .mcp.json at your project root:

{
  "mcpServers": {
    "framingui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@framingui/mcp-server@latest"]
    }
  }
}

Restart Claude Code. The MCP server is now running and the AI can query your design system.

If you're adding FramingUI to an existing project without using init, install the packages manually:

pnpm add @framingui/ui @framingui/core @framingui/tokens tailwindcss-animate

Then create .mcp.json with the config above.

What the AI Receives

When Claude queries the MCP server, it gets your token data in structured JSON—names, values, types, and descriptions. That structure is what makes the difference between a generic response and a design-system-aware one.

Without MCP:

<div className="p-4 bg-white rounded-lg shadow-md">
  <h3 className="text-lg font-semibold text-gray-900">John Doe</h3>
  <button className="mt-4 px-4 py-2 bg-blue-500 text-white rounded">
    View Profile
  </button>
</div>

With MCP:

<div className="bg-surface-elevated p-6 rounded-lg shadow-sm">
  <h3 className="text-lg font-semibold text-fg-primary">John Doe</h3>
  <button className="mt-4 px-spacing-4 py-spacing-2 bg-primary-500 text-white rounded-md">
    View Profile
  </button>
</div>

The difference is that every value in the second version maps to a token you defined. Change the token, and every AI-generated component using it updates on the next generation.

Token descriptions matter here. A token named color.primary.500 with a description "Primary brand color. Use for CTAs, links, and focus states" tells the AI both the value and the intent. It can choose primary-500 for a button and surface-elevated for a card background because it understands what each token is for.

Validating Existing Code

Beyond generation, MCP lets you validate existing components against your design system. Prompt the AI with a component you want to audit:

Check this component for design system compliance:

const Card = () => (
  <div style={{ background: '#ffffff', padding: '16px' }}>
    <h2 style={{ color: '#1a1a1a' }}>Title</h2>
  </div>
);

The AI queries your tokens and identifies the mismatches:

Hardcoded color #ffffff → use var(--bg-surface-base)
Hardcoded spacing 16px  → use var(--spacing-4)
Hardcoded color #1a1a1a → use var(--fg-primary)

This is useful for codebase audits, onboarding new team members to the token system, and catching regressions when someone introduces a hardcoded value.

Troubleshooting

AI still generates hardcoded values. Add explicit instruction to your prompt: "Use only tokens from the MCP server. Do not use hardcoded colors, spacing, or sizing." The AI will query tokens before generating.

MCP server not connecting. Verify the server starts cleanly:

npx -y @framingui/mcp-server@latest

Check that .mcp.json is at the project root and that you've restarted Claude Code after creating it. For debugging, check Help → Toggle Developer Tools → Console in Claude Code for MCP connection errors.

Tokens not found. Confirm your tokens.json path is correct relative to the project root. The MCP server reads the file on demand—if the path is wrong, queries return empty results rather than an error.

Using Your Existing Tokens

The MCP server works with any JSON token structure, not just tokens generated by FramingUI. If you already have tokens from Tokens Studio, Style Dictionary, or another source, point the server at your existing file.

For projects using Style Dictionary, the MCP server accepts a --format style-dictionary flag and reads the build output directly. For Tailwind-only projects, FramingUI can extract a token representation from your tailwind.config.js.

The goal is that wherever your design decisions currently live, the MCP server can make them available to your AI tools without requiring you to change your existing workflow.

Authentication

The six available themes (classic-magazine, dark-boldness, minimal-workspace, neutral-workspace, pebble, square-minimalism) require authentication. Run the login command after setup:

framingui-mcp login

This opens browser-based authentication and saves credentials to ~/.framingui/credentials.json. Alternatively, set the FRAMINGUI_API_KEY environment variable directly if you're working in a CI environment or prefer not to use browser authentication.

Token querying and design system features work immediately after init. Authentication is required specifically for the licensed theme catalog.