Storybook with AI: documenting components so an agent can use them

What is Storybook and why does an agent need it?

Storybook is a tool for developing and documenting interface components in isolation. Each component has stories, which are examples with specific props, and documentation that shows how it is used. For a designer, Storybook is where the real component can be seen in its states. It already has what an agent needs: names, props, variants and examples.

The problem is that without a structured channel, the agent has to read the source code and infer usage. Storybook MCP changes that access: it gives the agent tools to ask what exists and how it is used.

Which tools does it expose?

According to Storybook’s official documentation, the server groups its tools into three blocks:

The documentation also mentions review-create, which pushes a review of the current changes and requires Storybook’s review feature.

How do you turn it on?

According to the official documentation, there are four steps:

1. Install the addon: npx storybook add @storybook/addon-mcp. While the development server runs, the endpoint is at http://localhost:6006/mcp, although the port may differ in your project.
2. Enable the components manifest in .storybook/main.ts with features: { componentsManifest: true }.
3. Register the server in your agent. Storybook documents the setup for Claude Code, Gemini CLI, OpenAI Codex and VS Code Copilot.
4. Update AGENTS.md or CLAUDE.md to tell the agent to use the MCP tools.

To check it, ask the agent to list the documented components. If it calls docs-list, the connection works.

The step people most often miss is the second one: the manifest is off by default, and without it the documentation part is not available. If something fails, the manifest debugger (/manifests/components.html) shows the content and any generation errors.

How do you write a catalog an agent can use well?

Storybook’s best-practices guide gives concrete rules, and most of them are design work:

• One story, one concept. A story that shows every size and variant at once is the anti-pattern; split it.
• Explain the why. Describe when to use each story, not only what it shows. The guide’s own example: primary buttons handle the main action in a view, and there should be only one.
• Describe the component. A JSDoc comment above the component saying what it is for and when to use it, pointing to the alternative component (a button does not navigate; for navigation, use the link).
• Add @summary. Without a summary, the agent only gets the first 60 characters of the story description, so the opening words matter.
• Curate the context. Too little information hurts the agent, and so does irrelevant information. The !manifest tag lets you exclude a story that is an anti-pattern or a page meant only for humans.
• Write the information inside the MDX. The manifest is built by static analysis, so values imported from other files, such as color tokens, do not appear.

Why does it matter to a designer?

Because Storybook is where your component system becomes visible and verifiable. If you document a component’s intended use in Storybook, that documentation reaches the agent. If you do not, the agent keeps inventing. The same applies to stories for error, empty and disabled states: if they do not exist, the agent has no examples of how they should look.

Also, test-run gives you a concrete place to review accessibility. It does not replace your review, but it keeps a broken interaction from reaching a screen unnoticed. For the bigger picture of how agents use your system, see components and agents.

Can you share it with the team?

Yes, with limits. According to the documentation, if you publish your Storybook with Chromatic, the MCP server is published too: private if your Storybook is private, reachable only by invited project members. The alternative is to host it yourself with the @storybook/mcp library, which requires Node.js 20 or later and leaves you maintaining the server. In both cases only the documentation part is shared; the development and testing tools work only with your local Storybook.

When should you NOT use it?

• When your project uses a framework the manifest does not support. Check the support matrix first; the development and testing tools still work.
• When the team does not maintain the stories. An outdated catalog is worse than none, because the agent will treat it as the source.
• When the feature is used in production without review. Storybook indicates its AI capabilities are in preview and the API may change.
• When the component is not yet stable. Documenting something that will change means updating it twice.

Example

Illustrative example: a team has a Toast component with the variants info, success and error. In Storybook they write one story per variant and a usage sentence in the JSDoc: “Use it to confirm an action that already happened. Do not use it for errors that block the screen.” Then they ask an agent: “Show a notice when the draft is saved.” The agent calls docs-show for Toast, picks the success variant and uses the existing component. Then they ask for test-run on its new story and review the accessibility result.

What is left for you: confirming the notice appears in the right place in the flow, something no tool can decide for you.

Common mistakes

• Installing the addon without enabling the components manifest or writing stories. The catalog is empty and the agent has nothing to query.
• Writing only the happy-path story and skipping error, empty and loading states.
• Putting every variant in a single story, which the agent cannot make use of.
• Assuming support is the same across all frameworks.
• Letting the agent publish changes to stories without reviewing them.
• Trusting that passing accessibility tests means the screen is accessible. Tests catch technical issues, not the experience of use.

Sources

• Storybook: MCP overview for agents
• Storybook: best practices for AI
• Storybook: manifests
• Storybook: sharing your MCP server