Ground Generation in Your Real Component Registry with MCP

Tier: Advanced · Workflow area: Component development · Tools: shadcn registry MCP, Storybook MCP, Claude Code, Cursor

The failure mode this kills: the model confidently writes <DataTable columns={...} onRowSelect={...}> when your DataTable has neither prop. Hallucinated props typecheck-fail at best and silently no-op at worst. Grounding generation in a live registry turns component APIs from something the model guesses into something it reads.

When to use

• Your components live in a queryable sourcea shadcn-style registry, an internal registry endpoint, or Storybook with docs — and generated code keeps misusing them.
• Hallucinated props are a recurring review findespecially on large or fast-moving component APIs the model cannot memorize.
• Agents build multi-component screensthe win compounds when one task touches ten component APIs.
• You maintain the design systemregistry grounding makes your library the path of least resistance for every AI-assisted consumer team.

When NOT to use

• The instruction layer (pb-02) doesn't exist yetMCP grounding refines conditioned output; it can't rescue unconditioned output.
• A tiny, stable component seteight primitives that never change fit fine in an instruction file; the MCP indirection adds setup cost for little gain.
• Registry docs are stale or wronggrounding in bad metadata is worse than no grounding; fix the registry first.

The recipe

1. 1.

   Wire the shadcn MCP server into your agent. For a shadcn-based system (or any registry following the shadcn registry spec), one command per tool:

   Copy

   npx shadcn@latest mcp init --client claude
   npx shadcn@latest mcp init --client cursor
   

   This writes the MCP server entry into .mcp.json / Cursor's MCP config. Verify from inside the agent:

   Copy

   List the registries you can reach and show the first 10 components in the
   default registry, with one line each.
   

   Good output names your registry and lists real component names — not a generic shadcn catalog dump (unless that is your registry).

2. 2.

   Point it at your internal registry, not just the public one. In components.json:

   Copy

   {
     "registries": {
       "@acme": "https://registry.acme.dev/r/{name}.json"
     }
   }
   

   If your registry needs auth, export the token where the MCP server runs: ACME_REGISTRY_TOKEN=... claude. Re-run the listing prompt and confirm @acme/* components appear.

3. 3.

   Add Storybook MCP for prop-level truth on non-registry components. Registries know install payloads; Storybook knows rendered stories and argTypes. Run Storybook with the MCP addon enabled, then register it:

   Copy

   npm run storybook
   claude mcp add storybook --transport http http://localhost:6006/mcp
   

   Now the agent can answer "what props does OrdersTable accept and what do its stories look like" from the source of truth.

4. 4.

   Bake retrieval into the workflow with one instruction-file rule. Grounding only works if the agent actually looks things up:

   Copy

   Before using ANY @acme/ui component in generated code:
   1. Query the registry/Storybook MCP for its current props and variants.
   2. If the component is not installed, install it via the registry
      (npx shadcn@latest add @acme/<name>) — never re-implement it.
   3. If no matching component exists, stop and list the closest three
      candidates with their differences. Do not invent a component.
   

5. 5.

   Run the A/B that proves the wiring. Same task, MCP off vs. on:

   Copy

   Build an OrdersPage: filterable data table of orders (status, customer,
   total, date), row selection with bulk archive, date-range filter,
   pagination, empty state. Use our design system.
   

   With MCP on, a good transcript shows tool calls like search_items_in_registries("table"), view_items_in_registries("@acme/data-table"), then an install command, then code using only props that exist. Diff the two outputs and count hallucinated props — that number is your before/after metric.

6. 6.

   Verify by compilation, not vibes. The point of grounding is that this now passes:

   Copy

   npx tsc --noEmit && npx eslint src/features/orders --max-warnings 0
   

   Any remaining prop error means the registry metadata and the shipped types disagree — fix the registry, because every future generation reads it.

Make it yours

• shadcn/ui-based React systemthe golden path above; publish internal components through the registry spec (registry.json with registry:block / registry:component items) and both distribution and AI-grounding come free.
• Non-shadcn React, Vue, or Angular systemskip the shadcn CLI and lean on Storybook MCP as the grounding source (stories + argTypes exist for Vue and Angular too); "install" becomes "import from the package," so the instruction rule changes to query before import, and consider exposing a small custom MCP that serves your component manifest JSON.
• React Nativeno shadcn registry, but Storybook for RN or a generated component manifest (name, props, platforms, usage snippet) served over a custom MCP gives the same anti-hallucination effect; include platform availability per component so the agent doesn't use web-only primitives.

Quality check

• The agent's transcript shows registry/Storybook lookups before component usage — no lookups means the instruction rule isn't binding.
• Zero hallucinated props in the A/B task's grounded output, confirmed by tsc --noEmit passing untouched.
• Missing components trigger a stop-and-ask, not a hand-rolled look-alike — test by requesting a component you know doesn't exist.
• Registry metadata matches shipped typesspot-check three components against their published prop tables.
• .mcp.json is committed and reviewed so the whole team shares the wiring, with server versions pinned.