Skip to main content

Set up the Storybook MCP server

The Storybook MCP server gives coding agents your component library's documentation, read from a published Storybook, so they reuse your existing components with the right props instead of inventing new ones. This guide covers preparing your Storybook build and installing the server from the MintMCP MCP store.

Prerequisites​

  • A MintMCP admin account
  • A Storybook 10 project using a framework that supports the components manifest: any React framework, @storybook/angular-vite, or @storybook/vue3-vite
  • A published copy of that Storybook (a static build on any web host) reachable from MintMCP's runtime

The server reads the published build over HTTPS and never sees your source code, so it works from whatever your CI already deploys.

What the connector exposes​

The server runs the docs tools from Storybook's official MCP package:

ToolWhat it returns
docs-listEvery component and docs page in the Storybook, with their IDs
docs-showOne component's description, its stories with code, and its props
docs-show-storyThe full code of a single story

Storybook's development and testing tools, which preview stories and run story tests, need a Storybook dev server running on the developer's machine, so the hosted server doesn't include them. To use those, each developer adds @storybook/addon-mcp to their local Storybook as described in Storybook's MCP documentation.

Enable the components manifest​

The server reads the component manifest that Storybook generates at build time, so the published build has to include it.

  1. In .storybook/main.ts, enable the manifest:

    const config: StorybookConfig = {
      // ...
      features: { componentsManifest: true },
    };

    For @storybook/vue3-vite, also enable the experimental docgen server as described in Storybook's documentation.

  2. Rebuild and republish the Storybook the way you normally do (for example, storybook build in CI).

  3. Confirm the manifest is published by opening <your Storybook URL>/manifests/components.json in a browser. It should return JSON listing your components.

Add Storybook to MintMCP​

Storybook is pre-listed as a recommended server in the MintMCP MCP store, so MintMCP runs it on its own infrastructure and you only supply your Storybook's URL.

  1. In MintMCP, go to MCP store > Manage store.
  2. Find Storybook in the recommended servers list and click Install.
  3. Enter the Storybook URL, the address you open your published Storybook at, for example https://storybook.example.com. A link to a specific story also works, because the server keeps only the Storybook's root.
  4. Click Install.

The server reads the manifest from your published Storybook, so agents pick up each new Storybook release shortly after it's published, without reinstalling the connector.

Connect a private Storybook​

If your Storybook sits behind sign-in, give the server a header to send with its requests for the manifest. Any header your host accepts works, such as a bearer token, basic auth, or service-token headers from an access proxy.

  1. Open the Storybook server's settings page and click the Hosted Connector tab.
  2. On the Environment variables tab, add STORYBOOK_AUTH_HEADER, then click Save:
Value formSent as
Name: value, for example Authorization: Bearer abc123That header
Several Name: value pairs separated by \n, for example CF-Access-Client-Id: abc\nCF-Access-Client-Secret: xyzOne header per pair
A scheme and credentials with no header name, for example Bearer abc123 or Basic dXNlcjpwYXNzThe Authorization header

For HTTP basic auth, use Basic followed by the base64 of user:password. Don't put a username or password in the Storybook URL, because the server refuses to start with credentials in the URL.

The server sends this header only on requests to your Storybook URL, and it refuses redirects to another domain, so the credential never leaves your Storybook host.

Troubleshooting​

If the server doesn't start, its logs on the Hosted Connector tab name the setting to fix:

Log messageFix
STORYBOOK_URL must not contain a username or passwordRemove the credentials from the Storybook URL and add them as STORYBOOK_AUTH_HEADER with the Basic scheme, as described in Connect a private Storybook.
STORYBOOK_AUTH_HEADER line N is not "Name: value" or "<scheme> <credentials>"Rewrite that line in one of the forms in Connect a private Storybook.

Tool errors name the URL the server tried and what went wrong:

ErrorFix
returned 404. The Storybook has no components manifestEnable the manifest as described in Enable the components manifest, then republish. Check that the Storybook URL points at the Storybook's root.
The manifest refers to this file but it isn't publishedThe Storybook build was published only partly. Republish the whole build output.
returned 401 or returned 403The Storybook requires sign-in, or the file doesn't exist (hosts such as Amazon S3 answer 403 for missing files). Add STORYBOOK_AUTH_HEADER as described in Connect a private Storybook or check that its value is still valid, and check that the Storybook URL points at the Storybook's root.
did not return JSONThe URL served an HTML page instead of the manifest, usually a sign-in page or the wrong address. Open <your Storybook URL>/manifests/components.json in a browser to see what it returns.
redirects to ..., outside STORYBOOK_URLYour host redirects the Storybook to another domain, and the server follows redirects only within the Storybook URL's domain. Set the Storybook URL to the final address.
Could not reachMintMCP's runtime can't connect to the Storybook host. Check that the Storybook is published at a public address.

Security considerations​

  • The server only reads your published Storybook. It has no access to your repository, and no tool writes anything.
  • Everything in the published Storybook, including component source shown in stories and docs pages, becomes readable by every user of the connector. Control who can connect in MintMCP if the Storybook isn't public.
  • Store STORYBOOK_AUTH_HEADER credentials as you would any service token, scoped to read-only access to the Storybook, and rotate them by updating the environment variable.
  • The server removes the absolute file paths from the build machine that Storybook writes into the manifest, so CI runner paths aren't returned to agents.

Next steps​