Design System MCP

Every cloud project gets its own MCP endpoint. Point Claude Code, Codex, Cursor, VS Code, or Lovable 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 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. 1

    Add the endpoint to your client

    Claude Code, Codex, Cursor, VS Code, and Lovable each get their own snippet. None of them carries a credential:

    claude mcp add --transport http spektral-{project} \
      https://app.spektral.design/mcp/{team}/{project}
  2. 2

    Sign in

    The first time the client connects, it opens your browser. Sign in to Spektral and approve the client. It can then read every project you can see in that team, and it keeps working for as long as you stay a member. In Claude Code, run /mcp to start sign-in. In Lovable, add the endpoint under Connectors → Add custom → MCP server, leave authentication on OAuth, and click Add & authorize.

  3. 3

    Installs just work

    If your release is distributed as a tarball rather than to a registry, get_install_instructions returns a download link signed for that agent. It needs no token and expires after an hour. An agent that waits longer simply asks again. Releases published to a registry return a plain npm install.

Agent tokens, for CI and outside collaborators

Where nobody can sign in, such as a CI job or a contractor outside your team, mint an agent token on the same page instead. Name it after where it will live. The token is shown once, at creation, and only its hash is stored. Once it is on screen, the snippets switch to include it as an Authorization: Bearer header.

Tokens and Access

Read-only, by design

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

Scoped to one project

An agent token is minted for a single project. A signed-in client reaches only projects its user can see. Either way, a team in the URL that doesn't own the project is refused rather than silently served the right system: that would hide a real mistake.

Revoke instantly

Revoking an agent token cuts access immediately, and removing someone from the team does the same for their signed-in clients. 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