Design System MCP | Spektral Docs

Every cloud project gets its own MCP endpoint. Point Claude Code, Codex, Cursor, or VS Code at it and the agent building your product app can see what your design system already ships: components, specs, tokens, and the install command: instead of inventing a fourth button. Available on Pro and Enterprise.

Just Name Your Design System

Once a client is connected there is no special syntax, no tool names to memorise, and nothing to paste into a prompt. Ask for what you want and say which design system to build it with:

“Use the Acme design system to build our new marketing site.”

That works because the server introduces itself. It registers under your project's name, and the first thing a connecting agent reads is which design system this is, which release is current, and how it is expected to behave: check list_components before writing any UI, install the package rather than copying source, apply the system's tokens rather than hardcoding colours, and pin to the release it was told about.

So the agent goes and looks. It finds your Button, your Card, and the fact that you already ship a PricingTable: and builds the site out of them, on your tokens, importing from your package. The alternative, on a model with no connection to your system, is a site that looks approximately like your brand and shares no code with it.

Who It Is For

This server sits on the consuming side of the design system. It runs in the cloud, one endpoint per project, and it is read-only: it is for the product teams building on top of your system, not for the team building the system itself. That work still happens in the Spektral desktop app.

What the Agent Gets

Seven read-only tools. The server also introduces itself: it tells the connecting agent which design system it is, which release is current, and to check for an existing component before writing a new one.

list_components

Every component and recipe in the system with a one-line description. The first call an agent should make.

search_components

Find components whose name, description, or intent match a query: “date picker”, “banner”. Catches the near-duplicate that a name-only lookup misses.

get_component

Full detail for one component: what it's for, when to use it (and what to use instead), the decisions behind its API, props, events, states, keyboard behaviour, its accessibility contract, lifecycle status, and the import statement.

get_component_stories

The component's Storybook stories from the release: each story file's source and the named stories it exports. The system's own worked examples, so an agent composes with realistic props instead of guessing.

get_install_instructions

Package name, version, and install command. This is what stops an agent from pasting component source into your product repo and quietly forking the design system.

get_tokens

Colours, spacing, and typography as a ready-to-use :root stylesheet (css), a flat JS object (js), or the raw DTCG source (json). Takes a brand.

list_brands

The brands this system ships tokens for, when a product needs something other than the default.

list_versions

Released versions newest first, each with a changelog excerpt; pass a version to read its full changelog. The one tool that answers before a project has any releases: it's how a client discovers there are none.

Component specs are also exposed as MCP resources at spektral://{project}/components/{Name}. A tool call is a question; a resource is context a client can pin for a whole session, so an agent can keep a spec in front of it while it builds rather than re-fetching every turn.

It Serves Releases, Not Work in Progress

Every tool resolves against a release: never a branch head. An agent that built against 1.4.0 can rebuild the identical thing next month, and half-finished work on a branch never leaks into a product build. Every response names the release it came from so the agent can pin to it.

Pass version to any tool to read an older release. Omit it and you get the latest.

A project with no release says so. Rather than falling back to the working state, the server reports that nothing is published and tells the agent to ask you to cut a release. Cutting a release is the act that publishes your system to agents.

Connect a Client

Open your project in the browser and go to MCP. The page shows the endpoint, mints tokens, and generates a ready-to-paste snippet for each client. The endpoint is scoped to one project:

https://app.spektral.design/mcp/{team}/{project}

1
Mint an agent token
Name it after where it will live: a repo, a machine, a CI job. The token is shown once, at creation, and only its hash is stored. Lose it and you mint a new one; there is no way to recover it.
2
Copy the snippet for your client
Claude Code, Codex, Cursor, and VS Code each get their own, with your real token substituted while the page is on screen.
```
claude mcp add --transport http spektral-{project} \
  https://app.spektral.design/mcp/{team}/{project} \
  --header "Authorization: Bearer YOUR_TOKEN"
```
3
Export the token for installs
If your release is distributed as a tarball rather than to a registry, the download needs the same token: and the install command runs in a shell that can't see the header above. Export it:
```
export SPEKTRAL_MCP_TOKEN="YOUR_TOKEN"
```
Releases published to a registry return a plain npm install and need none of this.

Tokens and Access

Read-only, by design

Agent tokens carry components:read and tokens:read. Nothing an agent connects to this endpoint can change your design system.

Scoped to one project

A token is minted for a single project, and a token whose team doesn't match the URL is refused rather than silently served the right system: that would hide a real mistake.

Revoke instantly

Revoking cuts access immediately. The row stays on the page so you keep the audit trail of what had access and when it ended, alongside who created each token and when it was last used.

Pro and Enterprise

MCP access is a paid-plan feature. On the Free plan the endpoint is closed and the project's MCP page tells you so.

What It Looks Like in Practice

Starting something new. The agent orients itself once, then builds every page from what it found:

You: "use the Acme design system to build our new marketing site"

agent → list_components()
       ← 34 components, 6 recipes: release 1.4.0
agent → get_install_instructions()
       ← npm install @acme/ds@1.4.0
agent → get_tokens(format: "css")
       ← :root { --color-primary: ... }
agent → search_components("hero")
       ← HeroBanner, PricingTable, FeatureGrid
agent → get_component("HeroBanner")
       ← props, slots, responsive behaviour, examples

builds the site out of your components, on your tokens,
pinned to 1.4.0

Working in an existing codebase. Same tools, smaller scope:

You: "add a confirmation dialog to the checkout page"

agent → search_components("dialog")
       ← Modal, ConfirmDialog: release 1.4.0
agent → get_component("ConfirmDialog")
       ← props, events, keyboard behaviour, accessibility, usage do/avoid, import
agent → get_install_instructions()
       ← npm install @acme/ds@1.4.0
agent → get_tokens(format: "css")
       ← :root { --color-primary: ... }

writes UI that imports ConfirmDialog and uses your tokens
: instead of a hand-rolled div with hardcoded hexes