Chromatic MCP: what the hosted Storybook server gives agents

Every result on page one of "chromatic mcp" is either Chromatic, Storybook, or a competitor. There is no independent account of what you actually get.

Quick answer: Chromatic MCP is not a separate MCP server. It is Chromatic hosting Storybook's own MCP addon at a cloud endpoint, free, so your team can read component context without running Storybook locally. The part nobody states plainly: the published server exposes only the Docs toolset, which is 3 of the addon's 9 tools. The Development and Testing tools stay local. It is React-only, and while Chromatic's docs set the floor at "Storybook 10.3 or later", the addon version that npx storybook add installs today declares a hard peer dependency on Storybook 10.6.3.

What Chromatic MCP actually is

Chromatic's own framing, on chromatic.com/ai, is narrow and accurate: "Chromatic publishes Storybook MCP to a secure cloud endpoint to give agents UI context."

So the server is Storybook's. @storybook/addon-mcp is at 10.6.3, published 20 October 2026, MIT licensed. Chromatic's contribution is hosting, authentication and versioning around it. Storybook's own announcement post puts it in one line: "Chromatic supports publishing Storybook MCP out of the box for free. It also comes with quality checks, versioning, and secure authorization built-in."

That distinction matters because the two things fail differently. If a tool is missing, that is the addon and its gates. If authentication is failing, that is Chromatic.

What the hosted server gives agents, exactly

This is the sentence in Chromatic's MCP docs that should be at the top of every article on the subject:

Only the Docs tools are available in the published MCP server. The Development tools and Testing tools are only available when running the MCP server locally with Storybook's dev server.

The addon documents its tools in three toolsets totalling nine tools. The Docs toolset is three of them: docs-list returns the component index, docs-show returns detailed component documentation, and docs-show-story returns a full story with its documentation.

So the hosted server is a read-only component catalog for agents. Useful, and a third of the surface.

✅ What the published server does give you

• A component index and per-component documentation, over HTTP, from anywhere
• Context for teammates whose own project does not even use Storybook
• Composition, so a shared design system Storybook and an app Storybook arrive as one context
• Access control and authentication, which Chromatic describes as "built in"
• Versioning, so the context an agent reads matches a specific build

❌ What it does not give you

• stories-changed, stories-find-by-component or story-writing guidance, which are Development tools and stay local
• test-run, so no accessibility or component test execution from the hosted endpoint
• review-create, which is gated twice even locally
• Any design decision that is not already a built component

The version floor nobody has updated

Chromatic's docs state the requirements as "Storybook 10.3 or later" and "React". Storybook's announcement agrees: "Storybook 10.3 for React projects", with other frameworks "coming later this year".

That floor is now behind the package. @storybook/addon-mcp 10.6.3 declares storybook: ^10.6.3 as a hard peer dependency, so the version npx storybook add @storybook/addon-mcp installs today will not satisfy a peer check against Storybook 10.3. Since 10.6.0 the addon is version-locked to Storybook itself, which we covered in the Storybook MCP breakdown.

Practical reading: 10.3 is the floor for some addon version, not for the current one. If you are on 10.3 and want the hosted server, plan on the Storybook upgrade as part of the work.

One more peer dependency worth knowing: @storybook/addon-vitest at ^10.6.3, marked optional. That is the gate on test-run. Installing the MCP addon alone gives you a server with no test tool, hosted or local.

Setup, and the step that trips people

Chromatic's documented flow is five steps:

1. npx storybook add @storybook/addon-mcp
2. Run a Chromatic build, which deploys the MCP server alongside the published Storybook
3. Optionally enable composition by adding a refs section to your Storybook config
4. Install the MCP server in your coding agent with the mcp-add CLI
5. Test it with a prompt asking the agent to list all documentation

Step 4 is where it goes wrong. Chromatic's docs split authentication two ways: client ID metadata discovery for agents that support it, including VS Code and Copilot, and a static client ID published in the docs for the ones that do not, including Claude Code and Cursor.

Somebody hit exactly that wall and asked about it in Storybook discussion #34432: "I'm having trouble getting my Chromatic hosted Storybook MCP server working in Claude Code, seems to be due to OAuth." The thread has zero comments and is still marked unanswered.

If that is you, the answer is in Chromatic's MCP docs rather than Storybook's: Claude Code and Cursor are on the static client ID path, not discovery. Two more small things from the same page: composition refs keys reject upper-case characters, and the published server is a Chromatic build artifact, so no build means no endpoint.

Is it free?

Yes, for the publishing. The claim is Storybook's, not a vendor paraphrase: "Chromatic supports publishing Storybook MCP out of the box for free."

Chromatic itself is a paid visual testing platform with a free tier, and the MCP endpoint rides on the builds you are already publishing. There is no separate MCP line item in the docs. The honest caveat is that the thing generating the endpoint is a Chromatic build, so your snapshot usage is the real cost centre.

What it fixes, and what it does not

Chromatic's pitch beyond context is validation: "Chromatic validates what agents build and catches what they break." That is the visual testing product, and it is a genuine answer to agent-written UI, because the failure mode of an agent editing a component library is a regression three screens away from the diff.

A competitor's framing is the clearest statement of the boundary. UI Verify writes that "Chromatic ships an MCP too, but it serves Storybook component context for writing UI; it does not hand over the per-story diffs or accept" baselines. Take the source into account, and the structural point holds: the MCP surface is for building, the review surface is for approving, and they are not the same pipe.

The deeper limit is the one that applies to this whole category. Storybook MCP tells an agent what components exist. It cannot tell an agent what to do when no component fits, which is most of the interesting cases in a new product. Storybook's own sneak peek is precise about the scope: "Everything you've already built with Storybook is now available as machine-readable context."

Everything you have already built. If you have a mature React component library in Storybook, Chromatic MCP is a real upgrade over an agent grepping your source. If you are building the library, the agent needs design decisions before it needs a component index, and those live in a DESIGN.md rather than in a manifest.

The duply workflow

The two layers compose rather than compete. A DESIGN.md gives an agent the tokens and the reasoning: colors, type scale, spacing, and the rules for applying them. Storybook MCP, hosted by Chromatic or local, gives it the inventory of what already exists.

Start with the decisions. The duply library has 312 reviewed DESIGN.md files taken from real products, including Linear, Stripe and Vercel. Drop one in the repo root, then read give your AI agent a design system for the part that makes an agent actually respect it past the first few prompts. Add the MCP server once there is a component library worth indexing.

FAQ

Is Chromatic MCP a different server from Storybook MCP?

No. It is the same @storybook/addon-mcp server, published by Chromatic to a cloud endpoint with authentication, access control and versioning around it. Chromatic adds hosting and governance, not tools.

How many tools does the Chromatic-hosted MCP server expose?

Three: docs-list, docs-show and docs-show-story. Chromatic's docs state that only the Docs tools are available in the published server, and the addon's Development and Testing toolsets, six more tools, require running locally against Storybook's dev server.

Is Chromatic MCP free?

Publishing it is. Storybook's announcement says Chromatic "supports publishing Storybook MCP out of the box for free". It runs on your Chromatic builds, so the cost is whatever your Chromatic plan already costs.

What are the requirements?

Chromatic documents "Storybook 10.3 or later" and React. In practice the current addon, 10.6.3 as of 20 October 2026, declares a hard peer dependency on Storybook 10.6.3, so a fresh install needs the newer Storybook. Framework support beyond React is described by Storybook as coming later.

Why will Claude Code not connect to my Chromatic MCP URL?

Almost certainly OAuth client registration. Chromatic's docs route agents that support client ID metadata discovery, such as VS Code and Copilot, one way, and publish a static client ID for Claude Code and Cursor. An open Storybook discussion reports the same symptom with no reply, so the docs page is the place to look rather than the thread.

Does Chromatic MCP work with multiple Storybooks?

Yes, via composition. You add a refs section pointing at permalink URLs, and the agent reads the composed set as one context. Refs keys cannot contain upper-case characters.

Does it replace a design system file for AI agents?

No. It tells an agent what components exist and how they are documented. It carries no opinion about color, type scale, spacing or when to break a pattern, which is what a DESIGN.md holds. Teams running agents on UI work generally need both.

Summary

• Chromatic MCP is Storybook's MCP addon, hosted by Chromatic at a cloud endpoint, free to publish.
• The published server exposes 3 of the addon's 9 tools, all from the Docs toolset. Development and Testing tools stay local.
• React only, and the documented 10.3 floor is behind the current addon, which pins Storybook 10.6.3.
• The common failure is OAuth: Claude Code and Cursor use a static client ID from Chromatic's docs, not discovery.
• It gives agents an inventory, not a design language. Pair it with a DESIGN.md from the duply library.

Related reading

• Storybook MCP: the nine tools and the gates on them
• Design system MCP: what it is, who has one, what it can't do
• What is a DESIGN.md file?