Publish your Storybook MCP server

Without the right context, agents create new components instead of reusing existing ones, hallucinate APIs, and produce low-quality code that doesn’t align with your project’s conventions.

Storybook MCP improves generated code quality by giving agents project-specific context about your components and letting them self-correct with Storybook’s testing tools. Locally, the MCP runs via the Storybook dev server endpoint.

Chromatic manages deployments to make this MCP server accessible to your entire team and their coding agents. It also manages access control, ensuring only authorized collaborators can use your MCP server.

Setup guide

To deploy your Storybook MCP server with Chromatic, you need to need to be using Storybook 10.3 or later and use React.

1. Install the MCP addon

Run this command to install and register the Storybook MCP addon:

npx storybook add @storybook/addon-mcp

When running Storybook’s dev server, you can now access the MCP server at: http://localhost:6006/mcp (your port may be different).

2. Run a build to publish the MCP server

Simply run your Chromatic build as usual (either via CI or locally). This will automatically deploy your MCP server alongside your Storybook.

Once the build is complete, you will see a confirmation message with links to your published Storybook. The MCP server is published at the same URL as your Storybook on the /mcp route. For example:

https://642d765a7e8afcfb104268dc-mhlulncyca.chromatic.com/mcp

3. Enable composition

The most common scenario is building UI with components from multiple Storybooks. For example, an app with a local Storybook that consumes a design system with a published Storybook.

You can use Storybook composition to include content from both Storybooks in the local MCP server, allowing your agent to find and reference components from all composed Storybooks when generating UI.

To enable composition, add a refs section to your Storybook config. We recommend using your default branch’s permalink as the ref URL. For example:

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { StorybookConfig } from "@storybook/your-framework";

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ["../src/**/*.stories.@(js|jsx|ts|tsx)"],
  refs: {
    // 👇 Upper-case characters not supported in the refs key
    "chromatic-published-storybook": {
      // The title of your Storybook
      title: "Design System",
      // Permalink for your main branch
      url: "https://main--<appid>.chromatic.com",
    },
  },
};

export default config;

4. Install MCP server in your coding agent

Run the following command to configure the local MCP server for your coding agent. We only need to connect local MCP server because the remote Storybook is composed into the local Storybook.

npx mcp-add --type http --url "https://localhost:6006/mcp" --client-id "cdf3737dff9d485485968e50b63fd8b4" --scope project

Enable authentication

For private Storybooks, your coding agent must authenticate with Chromatic to access the MCP server. Chromatic uses CIMD to authenticate with tools that support it, such as VSCode and Copilot. For other coding agents, like Claude Code and Cursor, it uses a static client ID.

The mcp-add command above was already configured with the required client ID for authentication. The first time your agent connects to the MCP server you’ll be prompted to sign in with Chromatic. Follow the instructions in the authentication flow to grant access.

5. Run a prompt to test your MCP server

You’re all set! Let’s test it out. Start by explicitly asking the agent to run list-all-documentation on the MCP server. It should return a list of all components in your project (both local and those in the composed Storybooks).

Then run a typical prompt in your project such as the following:

Create a flight booking component that includes:

- An autocomplete component for choosing source and destination from the following list of airports:
  SYD: – Sydney Airport, Australia
  MEL: – Melbourne Airport (Tullamarine), Australia
  LAX: – Los Angeles International Airport, USA
  JFK: – John F. Kennedy International Airport, New York, USA
  LHR: – Heathrow Airport, London, UK
  CDG: – Charles de Gaulle Airport, Paris, France
  ATL: – Hartsfield–Jackson Atlanta International Airport, USA
  DXB: – Dubai International Airport, UAE
  HKG: – Hong Kong International Airport, Hong Kong
  BNE: – Brisbane Airport, Australia
  PER: – Perth Airport, Australia
  DFW: – Dallas Fort Worth International Airport, USA

- A toggle button for return vs one way
- One or two date selects that when clicked on triggers a popover with a calendar widget.

The calendar widget shouldn't allow selecting dates in the past and the return flight must be after the outward flight.

You should see the agent using the tools provided by your Storybook MCP server to find and reuse existing components.

Use the MCP server without a local Storybook

If you don’t have a local Storybook, you can connect your agent directly to the published MCP server. We recommend using your default branch’s permalink as the MCP server URL to ensure it stays up to date with your latest changes. For example: https://main--<appid>.chromatic.com/mcp

Connect your coding agent to the MCP server by running the following command, then following the authentication flow and test prompt described in step 5 above.

npx mcp-add --type http --client-id "cdf3737dff9d485485968e50b63fd8b4" --scope project

Frequently asked questions

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs)
import type { StorybookConfig } from "@storybook/your-framework";

const config: StorybookConfig = {
  // other config such as:
  // stories: [] etc.
  // ...
  features: {
    componentsManifest: false,
  },
};
export default config;

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs)
import type { StorybookConfig } from "@storybook/your-framework";

const config: StorybookConfig = {
  component: MyNoisyComponent,
  tags: ["!manifest"],
};
export default config;