Chromatic MCP Beta

The Chromatic MCP server https://mcp.chromatic.com/mcp connects your coding agent to your Chromatic account so that it can read your builds, test results, and project-level information such as quarantined tests and accessibility violations.

You log in once per agent, in your browser, using your Chromatic account. The server uses the Chromatic API on your behalf, and the agent inherits your account’s access and permissions.

Want to publish your Storybook’s MCP server? See Publish your Storybook MCP.

Your coding agent logs in once on chromatic.com, then sends each tool call with its token to the Chromatic MCP server at mcp.chromatic.com/mcp, which runs GraphQL against the Chromatic API as you

Tools

The server gives your agent tools that read your Chromatic data, such as getting the latest build on a branch (chromatic_get_latest_build), showing a story’s accessibility violations, and querying the Chromatic API. Skills chain these tools with your code.

Most Chromatic MCP tools only read your data. chromatic_mutate makes changes, and you choose whether to approve each one or let your agent act

Most tools are read-only, whereas chromatic_mutate is able to take actions on your behalf: accept or deny tests, quarantine or unquarantine them, and create projects. You have the control to approve each change yourself or allow the agent to make those calls for you.

For other limitations, see What can’t the MCP server do?

Install with the plugin

The Chromatic plugin for Claude Code, Codex, and Cursor is the recommended way to set up the server. It handles the configuration and installs the skills too. In Claude Code it also adds hooks that check your build after you push.

See Install the Chromatic plugin for your agent for detailed instructions.

Add the MCP server by hand

Adding the server by hand gives your agent the tools but not the skills. Use it when your agent can’t use plugins or when you want the server in Claude Desktop or claude.ai.

Claude Code

claude mcp add --transport http --scope user chromatic https://mcp.chromatic.com/mcp

Then start a session, run /mcp, choose chromatic, and approve the request in your browser. In the desktop app, send any first message before you run /mcp. --scope user makes the server available in every project.

Codex

codex mcp add chromatic --url https://mcp.chromatic.com/mcp
codex mcp login chromatic

Approve the request in your browser. codex mcp list should show OAuth next to chromatic. This needs Codex 0.148 or newer; check with codex --version.

Claude Desktop and claude.ai

This adds the server as a connector, which gives you the tools.

Open Customize » Connectors, click +, and choose Add custom connector.
Enter https://mcp.chromatic.com/mcp. Leave the OAuth client ID and secret empty.
Click Connect and approve the request on chromatic.com.

On a Team or Enterprise plan, an owner adds the connector once, then each person connects:

An owner opens Organization settings » Connectors » Add » Custom » Web and enters https://mcp.chromatic.com/mcp. Members cannot add custom connectors themselves.
Each member opens Customize » Connectors, finds Chromatic marked “Custom”, and clicks Connect. Everyone logs in to Chromatic as themselves, so nobody sees a project that their own account cannot.
Owners can set each tool to Always allow, Needs approval, or Blocked for the whole organization. Set the read-only tools to Always allow. Set chromatic_mutate to Needs approval to review each change, or Always allow to let agents act on their own.

Connectors run from Anthropic’s cloud. mcp.chromatic.com and www.chromatic.com are both public, so there is nothing to allowlist.

ChatGPT app

The ChatGPT app shares its setup with the Codex CLI.

Run the two commands under Codex.
Quit and reopen the app, then pick Codex in the sidebar.
Settings » MCP servers lists chromatic. If you skipped the login, use Authenticate there.

Other agents

In your agent’s MCP settings, add a remote server with the URL https://mcp.chromatic.com/mcp (Streamable HTTP). Leave any OAuth client ID and secret empty: your agent identifies itself with a client metadata document (CIMD) when it logs in, and your browser opens chromatic.com for you to approve the request. Any agent that supports remote MCP servers over Streamable HTTP and logs in with CIMD can connect; see Which clients are supported? for what Chromatic has tested.

Then ask “What time is it on the Chromatic server?” to check the connection.

To get the skills after adding the server by hand, see Get the skills.

Project ID

Every tool needs your Chromatic project ID. It lives in chromatic.config.json at the root of your repository, as projectId:

chromatic.config.json

{
  "projectId": "Project:64262bbd2f7d4ac4d7c5a7f3"
}

With the plugin, ask your agent to connect your Chromatic project, and the connect-project skill finds the project from your Git remote and writes the file. See Connect your project.

Without the plugin, copy the appId from any Chromatic project URL into that file. Prefix the hex ID with Project:, as in the example above.

In Claude Desktop or claude.ai, paste the project link into the chat.

A project token is not a project ID. Your agent never asks for your project token and the server refuses to read one, except the token of a project the agent just created, which comes back once so you can set up CI. See What can’t the MCP server do?.

Security and access

When you log in, your agent gets a token that acts as you. The token expires after 60 minutes and your agent refreshes it on its own. The agent is limited to only what your role in Chromatic allows, and only sees the projects you can see.

Revoke access

Log out an agent by clearing its login:

In Claude Code, run /mcp, choose chromatic, then Clear authentication.
In Codex, run codex mcp logout chromatic.

Remove a person: when someone is removed from your Chromatic account, or can no longer log in to Chromatic, their agents lose access too.

There’s no setting to turn off MCP access for a whole account. Access follows each person’s role, so manage it through collaborators and SSO.

If no one can log in through a browser, use a service client to call the Chromatic API directly. For cloud agents and software factories, see Run Chromatic with cloud agents.

Chromatic MCP vs. Storybook MCP

Your coding agent uses the Storybook MCP to write code with your components, and the Chromatic MCP to read builds, tests, and accessibility results

Chromatic MCP lives at https://mcp.chromatic.com/mcp, one server for all your projects. It serves your builds, tests, accessibility results, and Chromatic data. Use it to review, fix, and ship UI changes tested by Chromatic.

Storybook MCP lives at your published Storybook’s URL plus /mcp, one server per Storybook. It serves that Storybook’s own components and docs. Use it to generate code that uses your components correctly.

The Chromatic plugin does not connect the Storybook MCP, because its address is specific to your project. To set it up, see Publish your Storybook MCP.

For help with the Chromatic MCP server, the plugin, a build, or your account, contact Chromatic support. Include your agent, what you asked, and what it said.

Frequently asked questions

Which clients are supported?

Chromatic builds and tests the server with these clients:

Claude Code (terminal and desktop app): the plugin, skills, and hooks.
Codex CLI and the ChatGPT app: the plugin and skills, no hooks.
Cursor: the plugin and skills, no hooks. On a Teams or Enterprise plan, an admin imports the plugin once from https://github.com/chromaui/chromatic-plugins in the team marketplace settings. Each person then installs chromatic from Customize and signs in to Chromatic in the browser the first time the agent calls a tool.
Claude Desktop and claude.ai: the tools only, with no plugin, skills, or hooks.

Any other agent that logs in with CIMD can connect; see Other agents.

Can I run it without a person watching?

Yes. Pre-approve the read-only tools so the agent can read builds without asking. Pre-approve chromatic_mutate too if you want the agent to accept or quarantine tests on its own. For agents that run unattended, see Run Chromatic with cloud agents.

What can’t the MCP server do?

Reply to or resolve a reviewer comment. It reads comments and drafts a reply for you to post.
Start a build from the server. Builds run from your CI, or from your machine with run-build.
Change project settings, such as turning on accessibility tests or changing browsers. It gives you the link to the Manage screen.
Read your project token or Figma token. Copy a token from the project’s Manage screen yourself. The only exception is the token of a project the agent just created, which comes back with a note to save it as a CI secret.

Why are the skills missing when the tools work?

The server was likely added without the plugin, as a connector or with mcp add. Install the plugin or get the skills.

Why are the tools missing when the skills are installed?

Skills don’t install the MCP server. Add it separately, either with the plugin or by following Add the MCP server by hand.

Why does my agent get “refused for scope”?

Your login does not carry the permissions the tool needs. Log in again with /mcp or codex mcp login chromatic. In Claude Code, choose Clear authentication in /mcp first; in Codex, run codex mcp logout chromatic first. Until then, the skills give you a link to do it in Chromatic.

Why can’t my agent find my project?

It needs the project ID, which is the appId in a Chromatic project URL and not your project token. Run the connect-project skill and paste a link to the project. See Project ID.

Why are there no accessibility results?

Turn on accessibility tests for the project and run a new build. Builds from before you turn them on have no accessibility data, and your agent reports accessibility as “not measured”.

Why do calls fail after an update?

Restart the session so the agent reloads the tool list. In Claude Code you can also reconnect with /mcp.

Why does Claude Code say a tool result was saved to a file?

Claude Code does that for any answer over 50,000 characters, and the agent reads the file. Nothing is wrong. The server refuses answers over 100,000 characters rather than cutting them short, and the agent then asks for fewer fields or pages through the list.

Why doesn’t my agent check the build after a push?

Your agent checks on its own only in Claude Code, in a repository with a chromatic.config.json. Run connect-project to add one. See What the plugin runs on its own.

Why didn’t a plugin update arrive?

Your agent keeps a copy of the plugin. Run the update steps and restart the session, or remove and reinstall the plugin.

Edit page Submit feedback