How to Connect Your Design System to Claude Code, Cursor, Codex and VS Code

Four commands, one decision that matters, and the mistake most teams make on the way.

You have picked a design system MCP server. Connecting it takes about a minute. Getting it set up so your whole team benefits takes one extra decision, and that decision is the part worth reading.

The walkthrough below uses Claude Code's MCP commands because they are the clearest to write down. Cursor, Codex and VS Code follow the same shape with different file paths, and there is a section covering each of them further down.

Before you start

Four things, and the first one is the one people forget:

• A design system that exists in a platform. The MCP server serves what is in your account. If your tokens and components are still only in Figma, connect Figma's server instead, and come back to this when the system itself has somewhere to live.
• An account on that platform, with access to the design system you want to serve. The server connects as you, so an agent can only reach what you can reach. If you are on a team plan, check you are on the workspace holding the design system rather than a personal one.
• The endpoint URL, from your vendor's documentation rather than guessed. A wrong path is the most common failure and it looks like a connection problem rather than a typo.
• Your AI tool installed and signed in. Claude Code, Cursor, Codex or VS Code with Copilot. Open a terminal in a project directory. Any directory works, including an empty one.

Worth checking your plan before you start, because access varies. Supernova includes MCP on every plan including the free tier, so you can test the whole flow before anyone signs anything. Other platforms gate parts of it, so read the pricing page rather than assuming.

Add the server

Run this in your terminal, not inside a Claude session:

claude mcp add --transport http supernova https://mcp.supernova.io/mcp

Three parts matter:

• --transport http tells Claude Code the server is hosted at a URL rather than run as a local process. Design system servers are hosted, so this is almost always right.
• supernova is a name you invent. It labels the server's tools in Claude's output, so pick something you will recognise.
• The URL is the endpoint. Get it from your vendor's documentation rather than guessing.

Check it actually connected

The Added confirmation means the entry was saved, not that the server responded. Check:

claude mcp list

If you get a 404, Claude Code tells you the endpoint was not found and names the origin. Run claude mcp get supernova to see the full URL you configured and compare its path against the vendor's documented endpoint. Most 404s are a missing or extra path segment.

Sign in

Hosted design system servers sit behind authentication, because your design system is not public.

Start a session, open the MCP panel, pick the server, choose Authenticate:

/mcp

Your browser opens, you approve, and the status flips to connected. If the browser does not open, copy the URL from the terminal and open it yourself.

Some servers take a static token instead. Those want it at add time:

claude mcp add --transport http supernova https://mcp.supernova.io/mcp \
  --header "Authorization: Bearer <token>"

The decision that matters: scope

This is the part most teams get wrong, and it is the difference between one engineer having your design system and everyone having it.

claude mcp add defaults to local scope: private to you, active only in the project you ran it from. Fine for testing, useless for a team.

For your own machine across everything you work on:

claude mcp add --scope user --transport http supernova https://mcp.supernova.io/mcp

For the whole team:

claude mcp add --scope project --transport http supernova https://mcp.supernova.io/mcp

That writes .mcp.json to your repository root. Commit it. Every engineer who clones the repo gets prompted to approve the server, and then it connects for them too.

{
  "mcpServers": {
    "supernova": {
      "type": "http",
      "url": "https://mcp.supernova.io/mcp"
    }
  }
}

If you own a design system, read that file again. It is four lines of config, committed once, that puts your design system inside every engineer's agent. Adoption problems are usually distribution problems, and this is a distribution mechanism that costs you a pull request.

Scope is fixed when you add a server, so changing it means removing and re-adding:

claude mcp remove supernova --scope local

Check it is answering from your system

A connected server is not the same as a working one. Ask it something you already know the answer to:

Use the supernova server. What is the resolved value of our
primary button background token?

Two things to look for. The tool call in Claude's output should be labelled with your server name, which confirms the answer came from the server rather than the model's general knowledge. And the value should match what your design system actually says.

Naming the server in the prompt is only for this test. Normally Claude picks relevant tools on its own.

Then ask what it can do:

What tools does the supernova server give you?

The answer tells you the shape of the server. Tools starting with get and list are retrieval. create, update, delete and publish mean an agent can change things, which is worth knowing before you find out by accident.

Cursor, Codex and VS Code

Same server, same URL, different file. Three things differ and all three will silently break a config if you get them wrong.

Cursor uses the same shape as Claude Code, so the entry transfers directly:

{
  "mcpServers": {
    "supernova": { "url": "https://mcp.supernova.io/mcp" }
  }
}

VS Code uses servers, not mcpServers. Copying a Cursor config across without changing that key is the most common reason a VS Code server never appears:

{
  "servers": {
    "supernova": { "type": "http", "url": "https://mcp.supernova.io/mcp" }
  }
}

There is also a guided flow: MCP: Add Server from the Command Palette. VS Code asks you to trust a server the first time it starts.

Codex uses TOML rather than JSON, and the same config is shared across the ChatGPT desktop app, the Codex CLI and the IDE extension:

[mcp_servers.supernova]
url = "https://mcp.supernova.io/mcp"

Sign in with codex mcp login supernova.

Everything else in this guide still applies. Project-scoped config committed to the repo works the same way in all four, and it is still the setting worth changing.

Do not connect everything

Anthropic's own documentation is direct about the cost:

"Each connected server takes some space in Claude's context window because its tool names and server instructions load into every session."

Every server you add competes for the same budget as the work. Connecting Figma, Storybook, your design system platform, Linear, Sentry and a database means six sets of tool definitions loading before you have typed anything.

Connect what the project needs. Remove what it does not:

claude mcp remove <name>

When it breaks

For HTTP servers, a quick reachability check from your own machine:

curl -I https://mcp.supernova.io/mcp

A 404 or 405 means the server is up, since many MCP endpoints only answer POST. A 401 or 403 means it is up and you need to authenticate. No response means the URL or your network.

The setup you actually want

One line in .mcp.json, committed to the repo, so your design system arrives with the codebase.

Supernova's MCP server needs no plugin and no repo pull. The skills that teach an agent how to work with your design system are bundled into the server itself and listed as resources when something connects, so an agent that connects already knows how to use it.

See how it works.