Book a call

WritingAI-ready design systemsPart 7 of 20 in Making your design system AI-ready

Build an MCP server for your design system: a step-by-step guide

An MCP server lets any MCP-capable agent ask your design system precise questions instead of searching files. What MCP is, when a ready-made server is enough, and a complete, read-only server with four tools, tested in the Inspector and connected to Claude Code, Cursor and VS Code.

Diagram: an AI app's MCP client calls a design system server's tools, search_components, get_component and search_tokens, which read the token and component manifests.
On this pageThe problem: searching is guessing
  1. The problem: searching is guessing
  2. MCP in plain words
  3. Use a ready-made server, or build your own?
  4. Step 1: design the tools before writing code
  5. Step 2: set up the project
  6. Step 3: write the server
  7. Step 4: test it with the MCP Inspector
  8. Step 5: connect it to your agents
  9. What it looks like in use
  10. Local or hosted?
  11. Security basics
  12. How to check it works
  13. Common mistakes
  14. The short version
  15. Frequently asked questions
  16. Further reading

The short answer

An MCP server for your design system is a small program that gives AI agents a few precise tools, such as search_components, get_component and search_tokens, so they can ask your system questions instead of searching files and guessing. MCP (Model Context Protocol) is an open standard, so one server works with Claude Code, Cursor, VS Code with Copilot, Codex and other MCP clients. You can start with a ready-made server (Storybook's MCP addon for React, shadcn's for registry-based systems) or build your own in about 150 lines with the official SDK, reading the token and component manifests from parts 3 and 4. Keep it read-only, keep tools few and task-shaped, write tool descriptions as carefully as docs, and run it from the installed package so its answers match the version each repo uses.

  • The server shouldn't hold design decisions. It serves the manifests your build already makes.
  • Three to six tools is plenty. Every extra tool is something the agent has to choose between.
  • Part 7 of 20 in the series on AI-ready design systems.

The problem: searching is guessing

With a rules file (part 6), an agent knows your component index exists. But it still has to find the right file, open it, scan a long JSON list and decide. That works for small systems. With 90 components, 300 tokens and 40 pattern pages, an agent reading files will miss things, load too much, or skip the lookup altogether when it's in a hurry.

An MCP server replaces "go and find it" with "ask and get one clear answer". Here's the difference for a single question.

WITHOUT MCP

Five steps, 40,000 tokens

Search the repo for "date" → open a 2,000-line component index → open DatePicker.tsx → open DateRangePicker.tsx → open an old story that imports the legacy picker. Choose based on what it read last.

WITH MCP

Two calls, 1,500 tokens

search_components("pick a date range for a report") → DateRangePicker, with purpose. get_component("DateRangePicker") → props, rules and an example. Deprecated pickers never appear.

Illustration Token counts are illustrative; the shape of the difference is typical.

MCP in plain words

The Model Context Protocol is an open standard for connecting AI applications to data and actions. Anthropic introduced it in November 2024; it's now stewarded by the Agentic AI Foundation under the Linux Foundation, and supported by most major AI coding tools. The idea is the same as a USB port: build one connector and it works with every device that has the port.

Host
The AI applicationClaude Code, Cursor, VS Code, Codex…
Clients
Client → harborYour design system
Client → figmaFigma's server · part 8
Client → githubAny other server
Your server
ToolsFunctions the model can call: search_components
ResourcesData the app can read: harbor://tokens
PromptsReusable templates a person can pick: "Build a screen with Harbor"
Source of truth
tokens.agent.jsonPart 3
components.agent.json + detail filesPart 4
docs/*.mdPart 5
MCP's architecture. Your server offers three kinds of capability; the host decides when to use them.
New words

Tool: a function the model decides to call, with a name, a description and typed inputs. Resource: read-only data identified by a URI, usually attached by the app or the user rather than chosen by the model. Prompt: a template a person picks from a menu. stdio: the server runs as a local process and talks through standard input and output. Streamable HTTP: the server runs at a URL, so it can be hosted centrally.

For design systems, tools do almost all of the work, because they're what the model can reach for on its own in the middle of a task.

Use a ready-made server, or build your own?

OptionWhat it gives agentsBest whenLimits
Storybook MCP addon (@storybook/addon-mcp)Tools to list documented components and get their props, docs and story examples from Storybook's component manifestReact system with good stories and Storybook 10.3+React-first at the time of writing; knows what's in Storybook, not your tokens or patterns
shadcn MCPBrowse, search and install items from shadcn-compatible registriesYour system is distributed as a shadcn registryBuilt for installing source code, not for usage rules
Figma MCP serverDesign context, variables and Code Connect mappings from Figma filesDesign-to-code from Figma framesAbout the design file, not your code package; see part 8
Your own serverExactly the tools you design, over your manifests, docs and rulesSeveral frameworks, rich usage rules, tokens and patterns you want served togetherYou maintain it (but it's small)
These combine well: many teams run Storybook's or Figma's server alongside a small custom one for tokens and patterns.

If you use Storybook with React, try its addon first. It takes minutes:

npx storybook add @storybook/addon-mcp
# then, with Storybook running, the server is at http://localhost:6006/mcp

Its documentation tools (at the time of writing, list-all-documentation and get-documentation) are only as good as your stories and JSDoc, which is another reason the work in part 4 pays off. The rest of this article builds a custom server, which also teaches you what to look for in any ready-made one.

Step 1: design the tools before writing code

The most important decisions are which tools to offer and how to describe them. Tool descriptions are, in effect, instructions to the model: it reads them to decide whether and when to call each tool. Design them around the questions agents actually have, not around your data structures.

ToolQuestion it answersInputReturns
search_components"Which component fits this need?"A plain-language needUp to 5 current components: name, purpose, category
get_component"How do I use it correctly?"An exact nameProps, usage rules, accessibility, one example; or its replacement if deprecated
search_tokens"Which token for this job?"A need, optional type filterUp to 8 semantic tokens: name, CSS variable, description
get_pattern"How do we build this kind of screen?"A pattern name or needThe pattern page as Markdown
Four tools for Harbor. Each matches one question from the agent loop in part 2. A tool that checks code against the system can come later (part 9).
  • Describe when to call it, not just what it does. "Call this before writing any UI" changes behaviour; "Returns components" doesn't.
  • Return little, return clean. Five good matches beat fifty. Strip fields the agent doesn't need.
  • Hide what shouldn't be used. Search never returns deprecated components; get_component on a deprecated name returns the replacement.
  • Fail helpfully. "No component named Datepicker. Did you mean DatePicker or DateRangePicker?" lets the agent recover in one step.

Step 2: set up the project

The server lives in the design system repo and ships inside the package, so each product repo runs the version it has installed. We'll write it in plain JavaScript modules so there's no build step. The code follows version 1.x of the official TypeScript SDK; check the SDK's README if you're on a later major version, as APIs may differ.

# in the harbor package
npm install @modelcontextprotocol/sdk zod
// package.json (excerpt)
{
  "name": "@kestrel/harbor",
  "type": "module",
  "bin": { "harbor-mcp": "./mcp/server.mjs" },
  "files": ["dist", "mcp", "docs", "AGENTS.snippet.md"]
}

Step 3: write the server

Here's the complete server. Read the comments: most lines are descriptions and data handling, which is the point. The protocol itself is handled by the SDK.

#!/usr/bin/env node
// mcp/server.mjs: Harbor's MCP server. Read-only. Serves the manifests built in dist/.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { readFileSync, existsSync } from "node:fs";
import { fileURLToPath } from "node:url";

const root = fileURLToPath(new URL("../", import.meta.url));      // the installed package
const read = (p) => readFileSync(root + p, "utf8");
const index = JSON.parse(read("dist/components.agent.json"));
const { tokens } = JSON.parse(read("dist/tokens.agent.json"));

// Simple keyword scoring. Design system vocabulary is distinctive, so this goes a long way.
const words = (s) => s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2);
function rank(items, query, text, limit) {
  const q = words(query);
  return items
    .map((item) => ({ item, score: q.filter((w) => text(item).toLowerCase().includes(w)).length }))
    .filter((r) => r.score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, limit)
    .map((r) => r.item);
}
const json = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
const fail = (message) => ({ content: [{ type: "text", text: message }], isError: true });

const server = new McpServer({ name: "harbor", version: index.version });

server.registerTool("search_components", {
  title: "Search Harbor components",
  description:
    "Find Harbor design system components for a UI need. Call this before writing any UI " +
    "in a Kestrel product, then call get_component for the one you choose. " +
    "Only current components are returned.",
  inputSchema: {
    need: z.string().describe("What the UI must do, in plain words, e.g. 'confirm before deleting'"),
  },
  annotations: { readOnlyHint: true },
}, async ({ need }) => {
  const current = index.components.filter((c) => c.status !== "deprecated");
  const hits = rank(current, need, (c) => `${c.name} ${c.category} ${c.purpose}`, 5);
  return hits.length
    ? json(hits.map(({ name, category, purpose, status }) => ({ name, category, purpose, status })))
    : fail("No matching component. Categories: " + [...new Set(current.map((c) => c.category))].join(", ") +
           ". If nothing fits, tell the user instead of building a new component.");
});

server.registerTool("get_component", {
  title: "Get a Harbor component",
  description:
    "Get props, usage rules, accessibility requirements and an example for one Harbor component. " +
    "Follow its rules exactly. If the component is deprecated, the replacement is returned instead.",
  inputSchema: { name: z.string().describe("Exact component name, e.g. 'ConfirmDialog'") },
  annotations: { readOnlyHint: true },
}, async ({ name }) => {
  const entry = index.components.find((c) => c.name.toLowerCase() === name.toLowerCase());
  if (!entry) {
    const close = rank(index.components, name, (c) => c.name, 3).map((c) => c.name);
    return fail(`No component named ${name}.` + (close.length ? ` Did you mean ${close.join(" or ")}?` : ""));
  }
  if (entry.status === "deprecated") {
    return fail(`${entry.name} is deprecated. Use ${entry.replacedBy} instead; call get_component for it.`);
  }
  const file = `dist/components/${entry.name}.json`;
  return existsSync(root + file) ? json(JSON.parse(read(file))) : fail(`Details for ${entry.name} are missing.`);
});

server.registerTool("search_tokens", {
  title: "Search Harbor design tokens",
  description:
    "Find the semantic design token for a styling job (colour, spacing, radius, type). " +
    "Never hard-code values; use the returned cssVar, e.g. var(--color-text-secondary).",
  inputSchema: {
    need: z.string().describe("The job, e.g. 'helper text under a field' or 'padding inside a card'"),
    type: z.enum(["color", "dimension", "typography", "shadow", "duration"]).optional(),
  },
  annotations: { readOnlyHint: true },
}, async ({ need, type }) => {
  const pool = tokens.filter((t) => !t.deprecated && (!type || t.type === type));
  const hits = rank(pool, need, (t) => `${t.name} ${t.description ?? ""}`, 8);
  return hits.length
    ? json(hits.map(({ name, cssVar, type, description }) => ({ name, cssVar, type, description })))
    : fail("No matching token. Try describing the job differently, e.g. 'border of an input'.");
});

server.registerTool("get_pattern", {
  title: "Get a Harbor pattern",
  description: "Get guidance for a kind of screen or interaction: forms, empty states, tables, " +
    "settings pages, bulk actions. Call this when a task combines several components.",
  inputSchema: { pattern: z.enum(index.patterns) },
  annotations: { readOnlyHint: true },
}, async ({ pattern }) => ({ content: [{ type: "text", text: read(`docs/patterns/${pattern}.md`) }] }));

// A resource: the full token list, for apps that let users attach it.
server.registerResource("tokens", "harbor://tokens", {
  title: "Harbor semantic tokens",
  description: "Every semantic token with its CSS variable and description.",
  mimeType: "application/json",
}, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "application/json", text: read("dist/tokens.agent.json") }] }));

// A prompt: a template people can pick from their tool's menu.
server.registerPrompt("build_screen", {
  title: "Build a screen with Harbor",
  description: "Start a UI task with Harbor's workflow.",
  argsSchema: { screen: z.string().describe("What the screen is for") },
}, ({ screen }) => ({
  messages: [{ role: "user", content: { type: "text", text:
    `Build: ${screen}. First call get_pattern if a pattern applies, then search_components and ` +
    `get_component for each part, and search_tokens for any styling. Run pnpm check before finishing.` } }],
}));

await server.connect(new StdioServerTransport());
console.error(`harbor MCP server ${index.version} ready`);   // stderr: stdout carries the protocol

(The index's patterns field is a list of pattern names, such as ["forms", "empty-states", "tables"], added by the build alongside the component list.)

Watch out

With the stdio transport, never write to standard output (console.log) from the server. Standard output carries the protocol messages; a stray log line corrupts them and the client disconnects with a confusing error. Log to standard error (console.error) instead.

Step 4: test it with the MCP Inspector

Before connecting any agent, try the server in the MCP Inspector, the official visual testing tool. It lists your tools, shows their descriptions as the model will see them, and lets you call each one by hand.

npx @modelcontextprotocol/inspector node mcp/server.mjs
  1. Check the listing

    All four tools appear, with titles, descriptions and input fields. Read each description as if you were the model: is it clear when to call it?

  2. Call each tool with real needs

    Try "confirm before deleting", "show key numbers on a dashboard", "helper text colour". Are the top results right?

  3. Try the edge cases

    A misspelled name, a deprecated component, a need with no match. Each should return a helpful message, not a crash or an empty list.

Step 5: connect it to your agents

Each product repo adds a small project-level config. Because the command is npx harbor-mcp, it runs the server from that repo's installed version of Harbor, so an app still on version 6.2 gets 6.2's components, not the latest.

CLAUDE CODE

.mcp.json at the repo root

{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": ["harbor-mcp"]
    }
  }
}
CURSOR

.cursor/mcp.json

{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": ["harbor-mcp"]
    }
  }
}
VS CODE (COPILOT)

.vscode/mcp.json

{
  "servers": {
    "harbor": {
      "type": "stdio",
      "command": "npx",
      "args": ["harbor-mcp"]
    }
  }
}
REMOTE (OPTIONAL)

A hosted URL

{
  "mcpServers": {
    "harbor": {
      "type": "http",
      "url": "https://mcp.harbor
        .kestrel.example/mcp"
    }
  }
}

Commit these files so everyone on the team gets the server automatically. Most tools ask each person to approve a project's MCP servers the first time, which is a sensible security default. Then update the rules file's lookup line (part 6) to name the tools.

What it looks like in use

EngineerAdd a filter bar above the employees table: search by name, a department dropdown, and a "Clear filters" link.
Tool call · harbor.get_pattern{ "pattern": "tables" }
Result## Filtering a Table Put filters in a TableToolbar above the Table. Search first, then up to 3 Select filters, then "Clear filters" as a Button variant="ghost"…
Tool call · harbor.get_component{ "name": "TableToolbar" }
Result{ "props": { "children": …, "align": "start | between" }, "rules": ["Search field comes first", "Max 3 filters before 'More filters'"], … }
Tool call · harbor.get_component{ "name": "Dropdown" }
ResultDropdown is deprecated. Use Select instead; call get_component for it.
Tool call · harbor.get_component{ "name": "Select" }
Result{ "props": { "label": "string (required)", "options": …, "placeholder": … }, … }
AgentBuilt the toolbar with SearchField, Select (label "Department") and a ghost Button "Clear filters", following Harbor's table filtering pattern. Note: I first looked for Dropdown, which is deprecated, and used Select instead.
Illustration The deprecated lookup is caught by the server and redirected, which is the behaviour designed in step 1.

Local or hosted?

Local (stdio, from the package)Hosted (Streamable HTTP)
VersionMatches the version each repo installedOne version for everyone, unless you add a version parameter
SetupA config file per repo; nothing to runA service to deploy, monitor and authenticate
ReachCoding agents in your reposAlso web-based tools and app builders that can't run local processes
SecurityRuns on the developer's machine with their permissionsNeeds authentication (MCP specifies OAuth for HTTP servers) and access control
Usage dataHard to collectEasy: which tools are called, which searches find nothing
Start local. Add a hosted version when tools that can't run local processes need access, or when you want usage data to find gaps.

Security basics

  • Read-only tools. A design system server answers questions. It shouldn't edit files, run commands or call other services. Mark tools with readOnlyHint so clients can show that.
  • No secrets in responses. The server serves public-to-the-company design information only. No tokens, keys or internal credentials.
  • Treat contributed text as untrusted. Docs and metadata are written by many people. A malicious or careless line ("ignore previous instructions…") would reach the model through your tool. Review docs changes like code, and keep the server's responses to your own content.
  • Install only servers you trust. Third-party MCP servers run with your permissions. Prefer official ones (Figma, Storybook) and your own.

How to check it works

CheckHowPass when
Unit testsCall the search and lookup functions directly with 20 needs and expected answersCorrect component in the top 3 for 18+ of 20
Tool useRun your baseline tasks and read the transcriptsThe agent calls the tools before writing UI in every run
Output qualityScore off-system choices as in part 2Fewer than without the server, on the same tasks
Zero-result searchesLog searches that return nothing (stderr locally, metrics when hosted)Reviewed monthly; each is a docs gap or a missing component

If the agent never calls your tools, the problem is almost always the description or the rules file. Make the description say when to call it ("before writing any UI"), and name the tools in AGENTS.md.

Common mistakes

MISTAKE

One tool per component

Ninety tools named get_button, get_card… overwhelm the model's choice. One search tool and one get tool scale to any size.

MISTAKE

Returning everything

A search that returns the full detail of 20 components fills the context window. Return summaries; let the agent ask for detail.

MISTAKE

Design decisions in server code

Usage rules hard-coded in the server drift from the docs. The server should only read files the build generates.

MISTAKE

"Latest" for everyone

A hosted server that always serves the newest version tells a repo on 6.2 about props it doesn't have yet. Run locally, or accept a version.

The short version

  • An MCP server lets agents ask your design system precise questions through a standard any MCP client understands.
  • Try Storybook's MCP addon (React) or shadcn's (registries) first; build your own for tokens, patterns and rules.
  • Design three to six task-shaped tools; their descriptions are instructions to the model.
  • Serve the manifests your build already makes; hide deprecated items and fail with helpful suggestions.
  • Test in the MCP Inspector, ship it in the package, run it locally with npx, keep it read-only.

Next: Figma to code with AI, the design side: preparing your Figma library for the Figma MCP server and Code Connect.

Frequently asked questions

What is an MCP server for a design system?

A small program that exposes your design system to AI agents through the Model Context Protocol: tools to search components and tokens and get their usage rules, so agents look things up precisely instead of searching files and guessing.

Does Storybook have an MCP server?

Yes. The @storybook/addon-mcp addon serves a Storybook's component manifest to agents, with tools to list documented components and get their props, docs and examples. At the time of writing it supports React-based Storybooks, version 10.3 and later.

Which tools should a design system MCP server have?

A few task-shaped ones: search components by need, get one component's props and rules, search tokens by job, and get pattern guidance. Avoid one tool per component.

Should a design system MCP server run locally or be hosted?

Start locally, run from the installed package, so each repo gets answers for the version it uses. Host one over Streamable HTTP, with authentication, when web-based tools need access or you want usage data.

How do I test an MCP server?

Use the official MCP Inspector (npx @modelcontextprotocol/inspector) to list and call tools by hand, unit-test the search functions with real needs, and check agent transcripts to confirm the tools are called before UI is written.

Further reading