Publish your Storybook MCP server

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 use Storybook 10.3 or later and 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

Run a Chromatic build as usual, either via CI or locally, to automatically deploy your MCP server alongside your Storybook. If you don’t have a Chromatic project yet, then follow our quickstart guide to set up your first project and publish the 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

If your UI pulls components from multiple Storybooks, you can compose them into a single MCP server. For example, your app might have a local Storybook while consuming a design system from a published Storybook on a remote server.

Use composition to stitch together context from multiple Storybooks in your local MCP server. This allows agents to reference any component during UI generation.

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 the 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 to the 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: cdf3737dff9d485485968e50b63fd8b4.

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).

You should see the agent using the tools provided by your Storybook MCP server to find all the 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;

npx mcp-add --type http --url "https://<BRANCH>--<APP-ID>.chromatic.com/mcp" --client-id "cdf3737dff9d485485968e50b63fd8b4" --scope project

{
  "mcpServers": {
    "your-chromatic-storybook-mcp": {
      "type": "http",
      "url": "https://<BRANCH>--<APP-ID>.chromatic.com/mcp",
      "oauth": {
        "clientId": "cdf3737dff9d485485968e50b63fd8b4"
      }
    }
  }
}