An MCP Server for Your Design Tokens: Agents That Stay On-Brand

A design-tokens MCP (Model Context Protocol) server is a small program that exposes your design system's tokens — colors, spacing, radii, typography, motion curves — as structured, queryable tools that an AI coding agent can call while it writes UI code. Instead of an agent inferring a hex value from a screenshot or guessing at a spacing scale, it calls a tool such as get_token with a token name and gets back the exact value, its semantic role, and where it is allowed to be used. The result is generated components that stay on-brand by construction, not by luck.

This matters more every quarter, not less. As more UI work moves through AI agents — coding assistants, design-to-code tools, internal copilots — the bottleneck stops being whether the model can write a React component and becomes whether the model actually knows what your brand looks like. A tokens MCP server is the cleanest fix for that second problem, and it is a small enough build that most teams can ship a working version in a day or two.

Why Screenshots and Style Guides Aren't Enough

The default way most teams try to keep AI-generated UI on-brand is to paste a screenshot of the design system into a prompt, point the agent at a design file, or drop a brand-guidelines document into context. All three approaches share the same weakness: they hand the model a description of the design system and ask it to reverse-engineer exact values from that description. A model can eyeball a screenshot and land impressively close to the right shade of blue, but "impressively close" is not the same as the literal token value, and in a codebase with a hard rule against arbitrary hex codes or one-off pixel values, close enough is a lint failure and a design-review rejection.

Static documentation has a second, subtler problem: it drifts. A markdown file or PDF describing your spacing scale is a snapshot in time, and nothing keeps it synchronized with the CSS custom properties, Tailwind config, or Style Dictionary output that actually ship to production. Months after a token gets renamed or its value gets adjusted during a redesign, the document is quietly wrong, and every agent that reads it inherits that wrongness silently — there is no error, just UI that is subtly, confidently off-brand.

A tokens MCP server sidesteps both failure modes by treating the live token source — the actual CSS variables, JSON token files, or generated theme output — as the single source of truth, and exposing it through a protocol the agent queries at generation time rather than reads once from a stale document. The agent is not guessing what the design system looks like; it is asking the design system directly.

What MCP Actually Gives You Here

The Model Context Protocol is an open standard for connecting AI applications to external tools and data sources through a consistent client-server interface. An MCP server declares a set of tools (callable functions with typed inputs and outputs), optionally some resources (readable data, like a file or a database view), and the agent's host application — a coding assistant, an IDE integration, a chat client — discovers and calls them mid-conversation. The protocol itself is transport-agnostic and works the same whether the server runs locally over stdio or remotely over HTTP.

For design tokens specifically, this is a better fit than a plain REST API or a static file for one concrete reason: the agent can ask targeted, incremental questions instead of ingesting the entire token set up front. A well-designed tokens server lets the agent call list_token_categories, then get_tokens_by_category('color'), then get_token('color.danger.default') for the one value it actually needs for the button it is currently writing — instead of stuffing a 400-line token dump into context on every turn and hoping the model attends to the right line.

That incrementality also makes the server enforceable rather than merely advisory. Because every token lookup goes through a function call, you can log which tokens got requested, flag when an agent asks for a token that does not exist (a good signal it is about to invent one instead), and even have the tool call itself refuse to return raw values for tokens marked deprecated, nudging the agent toward the replacement.

Designing the Token Schema Before You Write Any Server Code

The single most important decision in this project happens before you touch the MCP SDK: how you structure the tokens themselves. Get this right and the server is a thin, almost mechanical wrapper. Get it wrong and no amount of clever tool design will stop an agent from picking the wrong value.

Use two tiers: primitive and semantic

Split tokens into a primitive tier — raw values like blue.500 or space.4 with no meaning attached — and a semantic tier that maps those primitives to a role: color.accent.default, color.surface.raised, space.card.padding. Agents should almost never be handed a primitive token directly; they should be steered toward semantic names, because a semantic name carries intent (this is "the accent color," not just "some blue") in a way a raw hex value never can. If your design system does not already separate these two tiers, doing so is worth the refactor on its own, independent of MCP — it is the same discipline that prevents a component from hardcoding #2563eb when it means "our accent color" and should re-theme automatically when the brand palette shifts.

Attach usage guidance, not just values

A token record that returns only a value is half as useful as one that also returns a one-line usage note and a short list of valid contexts: "color.danger.default — used for destructive-action text and icons, not backgrounds; pair with color.danger.subtle for the background fill." This is the piece screenshots and Figma links cannot convey nearly as reliably, and it is exactly the kind of tacit knowledge that lives in a senior designer's head. Writing it down once, as structured metadata, is what lets an agent apply it correctly on the thousandth component without a human in the loop.

Version the token set and mark deprecations explicitly

Add a version field to the token set and a status field per token (active, deprecated, experimental). When a token is deprecated, keep serving it — breaking the tool call is worse than serving a token you would rather phase out — but include a replacement pointer in its metadata and have the server surface that in its response. This gives you a graceful migration path: agents that read metadata will steer new code toward the replacement, while old code and slower-to-update agents keep working.

Building the Server: A Practical Tool Surface

You do not need many tools. A tokens MCP server earns its keep with a handful of well-designed calls rather than an exhaustive API surface. A workable minimum looks like this:

• list_token_categories — returns the top-level groups (color, spacing, typography, radius, shadow, motion) with a short description of each, so an agent can orient itself before drilling in.
• get_tokens_by_category(category) — returns every semantic token in a category with its value, usage note, and status. This is the call an agent makes when it is about to build a whole component and wants the full color or spacing palette in one shot.
• get_token(name) — returns a single token's full record. This is the call an agent makes mid-generation when it needs one specific value, e.g. while writing a single button variant.
• search_tokens(query) — a fuzzy or semantic search over token names and usage notes, for when the agent knows what it wants conceptually ("a warning-colored background") but not the exact token name.
• validate_usage(token, context) — optional but high-leverage: given a token name and a short description of where it would be used, returns whether that usage matches the token's intended context. This turns the server from a lookup table into a lightweight design-review gate the agent can consult before it writes a line of code.

On the implementation side, the actual server is usually a thin layer over whatever already generates your tokens. If you use Style Dictionary, Tokens Studio, or a plain CSS-variables file as the build output — including a Tailwind v4 setup that defines tokens inside an @theme block — the server's job is to parse that generated file once and serve it back through structured tools, rather than to become a second, independently maintained source of truth.

Wiring it to an existing token pipeline

Most teams already have a build step that turns design tool output (Figma variables, Tokens Studio JSON, a hand-maintained YAML file) into whatever the codebase actually consumes — CSS custom properties, a Tailwind theme object, Style Dictionary's platform outputs. The MCP server should read from that same generated artifact, not from a hand-copied duplicate. Point it at the built CSS variables file or the Style Dictionary JSON output, parse it once at startup (or on a file-watch reload in development), and build the in-memory lookup table the tools query against. This is what keeps the server honest: if the pipeline regenerates tokens with a new value, the MCP server picks it up on the next reload without anyone editing a second copy by hand.

For a Tailwind v4 codebase specifically — the kind of two-tier setup where primitives and semantic roles both live as CSS custom properties inside an @theme block — the parsing step is close to mechanical: read the generated CSS, extract each custom property and its value, and use naming convention (a --color-accent primitive versus a --semantic-color-accent-default alias, or whatever convention your system uses) to split primitives from semantic roles automatically. The server does not need to understand design semantics itself; it only needs to faithfully expose the structure your token pipeline already encodes.

A Worked Example: Wiring the Server Into an Agent Session

Once the server is running — typically as a local process the agent's host launches over stdio, or as an HTTP endpoint for a hosted setup — configuration is a matter of registering it with the MCP client, the same way you would register any other MCP server (a filesystem server, a database server, a browser-automation server). From that point on, the workflow inside an agent session looks roughly like this:

1. The developer prompts the agent to build a new "danger zone" card component for an account-deletion flow.
2. Before writing markup, the agent calls search_tokens with something like "destructive" or "danger" to see what is available, rather than assuming a color name.
3. It calls get_token for the specific semantic tokens that come back — border, background, and text colors for the danger role — and reads their usage notes to confirm background versus text-only usage.
4. It optionally calls validate_usage to confirm that using the danger-background token behind body copy (rather than just an icon) is within the intended pattern, catching a contrast mistake before it ships.
5. The generated component references the semantic token names directly — as CSS variables or Tailwind utility classes wired to those variables — rather than embedding literal hex values, so future theme changes propagate automatically.

The meaningful difference from a screenshot-based workflow is not just accuracy on this one component. It is that every subsequent component built in the same or a later session, by the same agent or a different one, goes through the identical lookup — so brand consistency stops depending on how good a screenshot happened to be that day, and starts depending on a token pipeline you already control.

Where This Fits Alongside Figma, shadcn/ui, and Headless Commerce

A tokens MCP server is not a replacement for a well-structured Figma file or a component library like shadcn/ui — it is the missing link between them and an AI agent that writes code. Figma variables are an excellent source of truth for designers; shadcn/ui and similar component approaches give you accessible, unstyled primitives that read from CSS variables rather than hardcoding style. The MCP server is what lets an agent bridge those two worlds correctly: pulling the right variable values out of the design source and applying them through the component layer, instead of improvising either half.

This is also where the pattern connects to headless commerce and Next.js storefronts more broadly. A storefront built with a component registry and a Medusa or similar headless backend already separates "what the page shows" from "how it's styled." A tokens MCP server extends that separation one step further: it lets an agent generating a new storefront section — a promotional banner, a variant picker, a checkout step — pull brand-correct styling automatically, the same way it would pull correct product data through the commerce API. The design system becomes just another well-typed service the agent talks to, rather than a document it has to remember.

If you are earlier in that journey and still working from a component library rather than a full token pipeline, a well-organized Figma kit is a reasonable starting point for defining the primitive and semantic tiers by hand before you invest in automation — our Figma UI kits are built with clearly named color, spacing, and type styles for exactly this reason, and translating that structure into a token JSON file is a natural first step toward the server described here. For teams already producing tokens as CSS variables, that same structure is what the MCP server should read from directly rather than re-deriving.

Common Pitfalls

A few mistakes show up repeatedly when teams build their first tokens server, and all of them are avoidable with a little foresight.

• Exposing primitives as the default lookup. If get_token returns raw primitives as readily as semantic tokens, agents will happily reach for blue.500 directly instead of color.accent.default, and you lose the entire point of the semantic tier. Make semantic tokens the default surface and require an explicit flag or separate tool to reach primitives.
• No usage notes, only values. A tool that returns a hex code and nothing else answers "what" but not "when," and agents will apply technically-correct-but-contextually-wrong tokens — an accent color used for an error state, for instance — without that guidance.
• Treating the server as a one-time export instead of a live reader. If the server's data is baked in at build time and never reloaded, it silently drifts the moment someone updates a token value, which is precisely the failure mode this whole approach exists to prevent.
• Skipping deprecation metadata. Removing an old token outright breaks every agent conversation and codebase reference still using it. Mark it deprecated with a replacement pointer instead, and remove it only after usage has actually migrated.
• Building a huge, undifferentiated tool surface. A dozen overlapping tools with subtly different signatures makes it harder, not easier, for an agent to pick the right call. Start with the five tools above and add more only when a real workflow needs them.

Where This Is Headed

Today, a tokens MCP server is mostly a way to keep AI-generated code visually consistent with an existing brand. The more interesting direction, and one worth building toward even if you do not need it yet, is treating the same server as the foundation for agent-generated component variants — an agent that does not just apply existing tokens correctly, but proposes a new semantic token (a rarer, brand-appropriate "info" surface color, say) through a propose_token tool that writes a draft entry for human review rather than inventing a value inline. That keeps a human in the loop for genuinely new design decisions while automating away the far more common case of an agent simply needing to know what your existing brand already looks like.

Polo Themes today focuses on Figma UI kits and Shopify OS 2.0 themes, and both are natural starting points for defining the token structure this pattern depends on — a clean two-tier token system in a Figma kit or a theme's settings schema translates directly into the schema described here. As more of that work moves toward headless, Next.js-based storefronts and AI-assisted design-to-code workflows, a tokens MCP server is one of the more durable pieces of infrastructure to have in place early, precisely because it does not care which agent, IDE, or design tool is on the other end of the call — it just answers the question correctly, every time it is asked.

Frequently Asked Questions

Do I need to already have a formal design-token system to build this?

Not a mature one, but you do need something machine-readable — a CSS variables file, a JSON export from a design tool, or a Tailwind theme config. If you only have colors and spacing scattered across component files today, the more valuable first step is consolidating those into a single token source; the MCP server is a thin layer on top of that consolidation, not a substitute for it.

Does this replace passing a screenshot or Figma link to an agent?

It replaces the screenshot as the source of exact values, but visual references are still useful for layout, composition, and overall feel — things a token server does not encode. The strongest workflow combines both: a visual reference for structure and intent, and the tokens server for the precise values that reference should resolve to.

Can this work with Figma directly instead of a separate token file?

Yes — if your Figma file uses variables (not just styles), you can build the server to read from Figma's REST API instead of a build artifact, fetching variable collections at request time or on a cache interval. Most teams still prefer reading from the built CSS or JSON output, since it guarantees the agent sees exactly what ships to production rather than an earlier or diverging design-file state.

Is this only useful for large design systems?

No — a small system with a few dozen tokens benefits just as much, arguably more, since a smaller team is less likely to have a dedicated design-systems engineer keeping documentation current by hand. The build effort scales with token count far less than the payoff does.