Your Design System Needs An MCP Server

A developer has proposed that design system teams build a Model Context Protocol (MCP) server to give AI coding agents accurate, structured access to component documentation and design tokens. Without an MCP server, AI tools like GitHub Copilot and Claude often guess how internal components work by scanning `node_modules` folders, leading to hallucinated APIs and incorrect code. The MCP server exposes "tools" that AI agents can invoke to retrieve precise component specifications, replacing guesswork with reliable context and reducing wasted tokens.

One of the best investments you can make for your design system right now is a Model Context Protocol MCP https://modelcontextprotocol.io/docs/getting-started/intro server. As AI models evolve they are becoming increasingly more capable, but using them effectively comes at a cost. Every token an AI wastes guessing how your components work is money left on the table. An MCP server gives an AI a set of tools it can use to look up exactly how to use your design system. Think of it like an API that an AI can call instead of guessing. In this article we'll talk about why this matters and how you can get started with your own. Before we get into it, there are some things about AI usage worth addressing. I've had my fair share of scepticism in the past, but recent model releases have made it increasingly difficult to argue that AI isn't a viable tool for the majority of workstreams, including building user interfaces. Most large language models are trained on public data scraped from the internet, which means your internal design system is largely invisible to them, especially if your documentation lives behind a corporate network. Without an MCP, an AI agent in any agentic coding tool such as GitHub Copilot https://github.com/features/copilot or Claude https://claude.ai/ will still try to use your system, often by poking around your node modules folder, filling in the gaps with its best guess. That’s where hallucinated component APIs come from. An MCP server doesn’t just make AI more useful for your design system, it directly addresses the trust problem by replacing guesswork with accurate, structured context. At the end of the day, users of a design system want a UI that adheres to brand guidelines as fast as possible. So why not empower them to use AI more effectively by giving their agents a recipe book for your system? It's a win-win: they get a layout that uses the right components and design tokens from the start, and you get more adoption without the usual hand-holding. An MCP server makes that possible by giving AI agents concrete tools to resolve those questions, producing code samples and design token usage that actually reflect your intent rather than an educated guess. Getting started with an MCP server is more straightforward than you might expect. Rather than endpoints, an MCP server exposes "tools" that an AI can invoke by name when it needs information. The key difference from a traditional API is that the response doesn't need to conform to a strict schema. Unlike a REST API where a client breaks if the shape of the data changes, an MCP tool can return loosely structured text or JSON and the AI will make sense of it. Your job is simply to point it toward the right information. If you're using Node you can use the @modelcontextprotocol/sdk https://www.npmjs.com/package/@modelcontextprotocol/sdk package to get started: js import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; const server = new McpServer { name: "my-design-system", version: "1.0.0", } ; // Tools are registered here - see examples below const transport = new StdioServerTransport ; await server.connect transport ; For a design system, you'll want to consider exposing tools along these lines: This gives an AI the ability to query your entire design system and drill down into specific component details as needed. How you build these tools will depend on your existing setup. If you're primarily building Web Components https://jamesiv.es/blog/frontend/javascript/2024/03/26/demystifying-web-components/ , you can connect directly to your Custom Elements Manifest, which already includes all of your components and their options in a machine-readable format: python import fs from "fs"; import { z } from "zod"; interface CustomElementDeclaration { kind: string; name: string; tagName?: string; summary?: string; customElement?: boolean; members?: Array<{ kind: string; name: string; type?: { text: string }; description?: string } ; slots?: Array<{ name: string; description?: string } ; events?: Array<{ name: string; description?: string } ; } interface CustomElementsManifest { modules: Array<{ declarations?: CustomElementDeclaration ; } ; } const manifest: CustomElementsManifest = JSON.parse fs.readFileSync "./custom-elements.json", "utf-8" ; const getDeclarations = : CustomElementDeclaration = manifest.modules.flatMap m = m.declarations ?? ; server.tool "list-components", "Lists all available components in the design system", {}, async = { const components = getDeclarations .filter d = d.kind === "class" && d.customElement .map d = { name: d.name, tagName: d.tagName, summary: d.summary } ; return { content: { type: "text", text: JSON.stringify components, null, 2 } , }; } ; server.tool "get-component", "Gets the full details of a component including its properties, slots, and events", { name: z.string .describe "The component class name or tag name" }, async { name } = { const component = getDeclarations .find d = d.name === name || d.tagName === name ; if component { return { content: { type: "text", text: Component "${name}" not found. } , }; } return { content: { type: "text", text: JSON.stringify component, null, 2 } , }; } ; If you're using Storybook, you can walk the Abstract Syntax Tree to reassemble stories as queryable examples. I wrote about this in another article in the context of validating server-side rendering https://jamesiv.es/blog/frontend/javascript/2026/03/13/headless-storybook-with-lit/ , but the same principles apply here. Alternatively you could use the Storybook MCP server https://storybook.js.org/docs/ai/mcp/overview plugin to expose your stories as tools without needing to write any custom code if you're using a language it supports. python import ts from "typescript"; import fs from "fs"; import path from "path"; import { glob } from "glob"; interface Story { name: string; source: string; } function extractStories filePath: string : Story { const code = fs.readFileSync filePath, "utf-8" ; const sourceFile = ts.createSourceFile filePath, code, ts.ScriptTarget.Latest, true ; const stories: Story = ; ts.forEachChild sourceFile, node = { if ts.isExportDeclaration node || ts.isVariableStatement node && node.modifiers?.some m = m.kind === ts.SyntaxKind.ExportKeyword { if ts.isVariableStatement node { for const decl of node.declarationList.declarations { if decl.initializer && ts.isObjectLiteralExpression decl.initializer { stories.push { name: decl.name.getText sourceFile , source: decl.initializer.getText sourceFile , } ; } } } } } ; return stories; } server.tool "get-component-examples", "Gets Storybook usage examples for a given component", { name: z.string .describe "The component name to find stories for" }, async { name } = { const files = await glob /${name}.stories.{ts,tsx} , { ignore: "node modules/ ", } ; if files.length { return { content: { type: "text", text: No stories found for "${name}". } , }; } const stories = extractStories files 0 ; return { content: { type: "text", text: JSON.stringify stories, null, 2 } , }; } ; Your server can be consumed by most agentic coding tools, though the configuration format varies depending on which one you're using. For VS Code, add a .vscode/mcp.json file and point it to either the HTTP address or stdio path: { "servers": { "my-design-system-mcp": { "type": "http", "url": "https://your-design-system.com/mcp" }, "my-other-mcp": { "command": "node", "args": "./mcp/server.js" } } } Once you have an MCP server running, your documentation becomes even more important since it's now being read by both humans and AI agents. This is a good opportunity to get specific. Rather than documenting that a Button component accepts a variant prop, document why certain combinations should be avoided - for instance, variant="ghost" is intentionally low-contrast and shouldn't be used as a primary call to action inside a form. An AI without that context will reach for it anyway because it looks like a valid option. The same applies to workarounds that have been passed around as word of mouth — if it lives only in someone's head or a Slack thread, an AI will never find it. The more focussed and opinionated your documentation is, the more focussed and opinionated your AI's output will be. Refactors that would otherwise take weeks can realistically come down to days or hours if the context is solid. If you want to unlock even more potential, pairing your MCP server with Figma Code Connect https://jamesiv.es/blog/frontend/javascript/2025/09/21/custom-elements-manifest-and-figma-code-connect/ is worth the investment. Figma has its own MCP server https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server that can read design specs directly. Since you can connect multiple MCP servers at once, an AI can take a design spec, identify the right components to use, and then query your design system MCP for the implementation details and edge cases. The result is a workflow where AI moves from design to code with much less back and forth. The teams that will get the most out of AI tooling are the ones who give it the best context to work with. A well-maintained design system with an MCP server is exactly that: a direct line between your standards and the tools your engineers use every day. The abstraction and consistency that design systems have always provided become significantly more valuable when AI can consume them reliably. This applies beyond design systems too, any well-documented library benefits from the same approach. Design systems have always been about giving teams a shared language. The MCP server just means AI gets to speak it too.