Skip to content
Redpanda UI
Esc
↑↓navigate↵open⌘Jpreview
On this page

MCP

How to use the shadcn MCP with Redpanda UI Registry.

We strongly recommend configuring your AI Agent with the shadcn MCP server and the following guidelines. This gives your AI Agent full context about the registry — component discovery, documentation, code preview, and installation — all natively supported.

1. Add the shadcn MCP

The shadcn MCP server works out of the box with the @redpanda registry configured in your components.json. Make sure you have set up your project first.

Replace /absolute/path/to/project in every example below with the absolute path to your project containing components.json. The explicit --cwd keeps the server attached to that project even when your editor or desktop client launches it from another directory. The examples pin the verified shadcn CLI version.

Copy and paste the code into .cursor/mcp.json:

json
{  "mcpServers": {    "shadcn": {      "command": "bun",      "args": ["x", "--cwd", "/absolute/path/to/project", "--bun", "shadcn@4.22.1", "mcp"]    }  }}

Run the following command in your terminal:

bash
claude mcp add shadcn -- bun x --cwd /absolute/path/to/project --bun shadcn@4.22.1 mcp

Copy and paste the code into .vscode/mcp.json:

json
{  "servers": {    "shadcn": {      "command": "bun",      "args": ["x", "--cwd", "/absolute/path/to/project", "--bun", "shadcn@4.22.1", "mcp"]    }  }}

Copy and paste the code into Claude/claude_desktop_config.json:

json
{  "mcpServers": {    "shadcn": {      "command": "bun",      "args": ["x", "--cwd", "/absolute/path/to/project", "--bun", "shadcn@4.22.1", "mcp"]    }  }}

The shadcn MCP server automatically discovers the @redpanda registry from your components.json and exposes all components to your AI agent — including documentation, code, and install commands.

2. Add the following guidelines to your AI Agent

We strongly recommend you add these code style guidelines to your agent, as it ensures proper UI best practices are followed every time you want to build a UI.

Create a .cursor/rules/ui.md file and paste the following code:

.cursor/rules/ui.md
---name: Redpanda UI Registrywhen: Whenever a user wants to build a UI or requests code examples or documentation for the Redpanda UI Registry (or design system or UI library)---# UI development guide
## Discover the real API- Browse @redpanda with the shadcn MCP server before choosing components.- Read the installed source and current component documentation. Do not invent props, exports, callbacks or package scripts.- Check components.json for the registry installation path and aliases.- Install or update components through the shadcn CLI; include their dependency closure.- Follow the breaking migration guide when replacing older copied components. Overwrite does not delete retired files.
## Write strict, working UI- Use functional React components and named exports unless the framework requires a default export.- Use registry controls for forms and interactive UI. Use Button for actions and ButtonLink or the real router Link for navigation.- Give each action a real handler, submit behavior or truthful disabled state. Do not present disconnected controls or simulated operations as successful backend work.- Use semantic HTML and persistent labels. Name icon actions and describe why unavailable actions are disabled.- Keep information-only help keyboard- and touch-accessible with Popover. Tooltip is a supplementary visual label, not an accessible description.- Forward native attributes and React 19 refs without nested interactive controls.- Model loading, empty, error and success states. Report asynchronous failures visibly; do not swallow them.- Use schemas, type guards and generics at external data seams. Keep unvalidated data unknown, not any.- Preserve discriminated unions and handle every variant exhaustively.- Keep rendering pure. React Compiler owns memoization here; do not add useMemo, useCallback or memo as routine optimizations, or depend on cache identity for correctness.
## Keep appearance at its owner- Select documented component variants, sizes and anatomy instead of repainting children.- Use Tailwind design tokens and spacing scales. Keep consumer className to permitted layout and outer spacing.- Do not move forbidden paint into wrapper elements, utility helpers, dynamic class factories or one-off tokens.- Pass runtime layout data through the component's existing typed CSS custom-property protocol, not ordinary inline appearance.- When a real shared design is missing, repair its registry owner and document the finite API. Do not patch copied consumer primitives to evade checks.- Keep viewport layouts responsive, native focus visible and reduced-motion behavior intact.
## Prove the behavior- Write a failing public-behavior test before a bug fix or behavior change. Use the existing strongest test owner.- Use userEvent.setup, role-based queries and awaited assertions for unit/integration interactions.- Exercise visible changes in the actual app with Playwright, including keyboard, touch where relevant, narrow layouts and both themes.- Repeat native open/close, navigation and asynchronous lifetimes where stale state or cleanup can fail.- Wait for actual app readiness, fonts and settled animations. Avoid fixed-duration and network-idle waits.- Keep independent assertions. Do not replace failing behavior checks with source-text scans, weaker assertions or refreshed snapshots.
## Enforce the repository gates- Repair diagnostics. Do not add TypeScript suppression comments, lint-disable comments, React Compiler opt-outs, shadow configurations, exclusions or baselines.- A new tool rule requires an explicit applicability decision in the rule ledger. Configuration and compiler drift must fail closed.- In this registry repository, run the commands below. type:check requires both pinned TSRS and TypeScript 7.1 dev-canary tsc.
```bashbun run lint:fixbun run quality:gatebun run buildbun run --filter=docs validate```
- In a consuming application, inspect its package.json and run its actual lint, typecheck, test, build and browser scripts. Do not assume the registry scripts exist there.- Before handoff, review the diff, preserve licenses, report the checks actually run and document breaking migrations and verification gaps.

Create a .claude/UI.md file and paste the following code:

.claude/UI.md
# UI development guide
## Discover the real API- Browse @redpanda with the shadcn MCP server before choosing components.- Read the installed source and current component documentation. Do not invent props, exports, callbacks or package scripts.- Check components.json for the registry installation path and aliases.- Install or update components through the shadcn CLI; include their dependency closure.- Follow the breaking migration guide when replacing older copied components. Overwrite does not delete retired files.
## Write strict, working UI- Use functional React components and named exports unless the framework requires a default export.- Use registry controls for forms and interactive UI. Use Button for actions and ButtonLink or the real router Link for navigation.- Give each action a real handler, submit behavior or truthful disabled state. Do not present disconnected controls or simulated operations as successful backend work.- Use semantic HTML and persistent labels. Name icon actions and describe why unavailable actions are disabled.- Keep information-only help keyboard- and touch-accessible with Popover. Tooltip is a supplementary visual label, not an accessible description.- Forward native attributes and React 19 refs without nested interactive controls.- Model loading, empty, error and success states. Report asynchronous failures visibly; do not swallow them.- Use schemas, type guards and generics at external data seams. Keep unvalidated data unknown, not any.- Preserve discriminated unions and handle every variant exhaustively.- Keep rendering pure. React Compiler owns memoization here; do not add useMemo, useCallback or memo as routine optimizations, or depend on cache identity for correctness.
## Keep appearance at its owner- Select documented component variants, sizes and anatomy instead of repainting children.- Use Tailwind design tokens and spacing scales. Keep consumer className to permitted layout and outer spacing.- Do not move forbidden paint into wrapper elements, utility helpers, dynamic class factories or one-off tokens.- Pass runtime layout data through the component's existing typed CSS custom-property protocol, not ordinary inline appearance.- When a real shared design is missing, repair its registry owner and document the finite API. Do not patch copied consumer primitives to evade checks.- Keep viewport layouts responsive, native focus visible and reduced-motion behavior intact.
## Prove the behavior- Write a failing public-behavior test before a bug fix or behavior change. Use the existing strongest test owner.- Use userEvent.setup, role-based queries and awaited assertions for unit/integration interactions.- Exercise visible changes in the actual app with Playwright, including keyboard, touch where relevant, narrow layouts and both themes.- Repeat native open/close, navigation and asynchronous lifetimes where stale state or cleanup can fail.- Wait for actual app readiness, fonts and settled animations. Avoid fixed-duration and network-idle waits.- Keep independent assertions. Do not replace failing behavior checks with source-text scans, weaker assertions or refreshed snapshots.
## Enforce the repository gates- Repair diagnostics. Do not add TypeScript suppression comments, lint-disable comments, React Compiler opt-outs, shadow configurations, exclusions or baselines.- A new tool rule requires an explicit applicability decision in the rule ledger. Configuration and compiler drift must fail closed.- In this registry repository, run the commands below. type:check requires both pinned TSRS and TypeScript 7.1 dev-canary tsc.
```bashbun run lint:fixbun run quality:gatebun run buildbun run --filter=docs validate```
- In a consuming application, inspect its package.json and run its actual lint, typecheck, test, build and browser scripts. Do not assume the registry scripts exist there.- Before handoff, review the diff, preserve licenses, report the checks actually run and document breaking migrations and verification gaps.

Then, reference it in your root CLAUDE.md file:

CLAUDE.md
@.claude/UI.md

Create a .github/copilot-instructions.md file and paste the following code:

.github/copilot-instructions.md
# UI development guide
## Discover the real API- Browse @redpanda with the shadcn MCP server before choosing components.- Read the installed source and current component documentation. Do not invent props, exports, callbacks or package scripts.- Check components.json for the registry installation path and aliases.- Install or update components through the shadcn CLI; include their dependency closure.- Follow the breaking migration guide when replacing older copied components. Overwrite does not delete retired files.
## Write strict, working UI- Use functional React components and named exports unless the framework requires a default export.- Use registry controls for forms and interactive UI. Use Button for actions and ButtonLink or the real router Link for navigation.- Give each action a real handler, submit behavior or truthful disabled state. Do not present disconnected controls or simulated operations as successful backend work.- Use semantic HTML and persistent labels. Name icon actions and describe why unavailable actions are disabled.- Keep information-only help keyboard- and touch-accessible with Popover. Tooltip is a supplementary visual label, not an accessible description.- Forward native attributes and React 19 refs without nested interactive controls.- Model loading, empty, error and success states. Report asynchronous failures visibly; do not swallow them.- Use schemas, type guards and generics at external data seams. Keep unvalidated data unknown, not any.- Preserve discriminated unions and handle every variant exhaustively.- Keep rendering pure. React Compiler owns memoization here; do not add useMemo, useCallback or memo as routine optimizations, or depend on cache identity for correctness.
## Keep appearance at its owner- Select documented component variants, sizes and anatomy instead of repainting children.- Use Tailwind design tokens and spacing scales. Keep consumer className to permitted layout and outer spacing.- Do not move forbidden paint into wrapper elements, utility helpers, dynamic class factories or one-off tokens.- Pass runtime layout data through the component's existing typed CSS custom-property protocol, not ordinary inline appearance.- When a real shared design is missing, repair its registry owner and document the finite API. Do not patch copied consumer primitives to evade checks.- Keep viewport layouts responsive, native focus visible and reduced-motion behavior intact.
## Prove the behavior- Write a failing public-behavior test before a bug fix or behavior change. Use the existing strongest test owner.- Use userEvent.setup, role-based queries and awaited assertions for unit/integration interactions.- Exercise visible changes in the actual app with Playwright, including keyboard, touch where relevant, narrow layouts and both themes.- Repeat native open/close, navigation and asynchronous lifetimes where stale state or cleanup can fail.- Wait for actual app readiness, fonts and settled animations. Avoid fixed-duration and network-idle waits.- Keep independent assertions. Do not replace failing behavior checks with source-text scans, weaker assertions or refreshed snapshots.
## Enforce the repository gates- Repair diagnostics. Do not add TypeScript suppression comments, lint-disable comments, React Compiler opt-outs, shadow configurations, exclusions or baselines.- A new tool rule requires an explicit applicability decision in the rule ledger. Configuration and compiler drift must fail closed.- In this registry repository, run the commands below. type:check requires both pinned TSRS and TypeScript 7.1 dev-canary tsc.
```bashbun run lint:fixbun run quality:gatebun run buildbun run --filter=docs validate```
- In a consuming application, inspect its package.json and run its actual lint, typecheck, test, build and browser scripts. Do not assume the registry scripts exist there.- Before handoff, review the diff, preserve licenses, report the checks actually run and document breaking migrations and verification gaps.
  1. Click on “Set project instructions.”
  2. Copy and paste the instructions below into “Project Instructions” and click “Save instructions.”
Project Instructions
# UI development guide
## Discover the real API- Browse @redpanda with the shadcn MCP server before choosing components.- Read the installed source and current component documentation. Do not invent props, exports, callbacks or package scripts.- Check components.json for the registry installation path and aliases.- Install or update components through the shadcn CLI; include their dependency closure.- Follow the breaking migration guide when replacing older copied components. Overwrite does not delete retired files.
## Write strict, working UI- Use functional React components and named exports unless the framework requires a default export.- Use registry controls for forms and interactive UI. Use Button for actions and ButtonLink or the real router Link for navigation.- Give each action a real handler, submit behavior or truthful disabled state. Do not present disconnected controls or simulated operations as successful backend work.- Use semantic HTML and persistent labels. Name icon actions and describe why unavailable actions are disabled.- Keep information-only help keyboard- and touch-accessible with Popover. Tooltip is a supplementary visual label, not an accessible description.- Forward native attributes and React 19 refs without nested interactive controls.- Model loading, empty, error and success states. Report asynchronous failures visibly; do not swallow them.- Use schemas, type guards and generics at external data seams. Keep unvalidated data unknown, not any.- Preserve discriminated unions and handle every variant exhaustively.- Keep rendering pure. React Compiler owns memoization here; do not add useMemo, useCallback or memo as routine optimizations, or depend on cache identity for correctness.
## Keep appearance at its owner- Select documented component variants, sizes and anatomy instead of repainting children.- Use Tailwind design tokens and spacing scales. Keep consumer className to permitted layout and outer spacing.- Do not move forbidden paint into wrapper elements, utility helpers, dynamic class factories or one-off tokens.- Pass runtime layout data through the component's existing typed CSS custom-property protocol, not ordinary inline appearance.- When a real shared design is missing, repair its registry owner and document the finite API. Do not patch copied consumer primitives to evade checks.- Keep viewport layouts responsive, native focus visible and reduced-motion behavior intact.
## Prove the behavior- Write a failing public-behavior test before a bug fix or behavior change. Use the existing strongest test owner.- Use userEvent.setup, role-based queries and awaited assertions for unit/integration interactions.- Exercise visible changes in the actual app with Playwright, including keyboard, touch where relevant, narrow layouts and both themes.- Repeat native open/close, navigation and asynchronous lifetimes where stale state or cleanup can fail.- Wait for actual app readiness, fonts and settled animations. Avoid fixed-duration and network-idle waits.- Keep independent assertions. Do not replace failing behavior checks with source-text scans, weaker assertions or refreshed snapshots.
## Enforce the repository gates- Repair diagnostics. Do not add TypeScript suppression comments, lint-disable comments, React Compiler opt-outs, shadow configurations, exclusions or baselines.- A new tool rule requires an explicit applicability decision in the rule ledger. Configuration and compiler drift must fail closed.- In this registry repository, run the commands below. type:check requires both pinned TSRS and TypeScript 7.1 dev-canary tsc.
```bashbun run lint:fixbun run quality:gatebun run buildbun run --filter=docs validate```
- In a consuming application, inspect its package.json and run its actual lint, typecheck, test, build and browser scripts. Do not assume the registry scripts exist there.- Before handoff, review the diff, preserve licenses, report the checks actually run and document breaking migrations and verification gaps.
  • Figma Remote MCP
  • Playwright MCP (for exposing the rendered UI to the agent)

4. Restart your AI Agent

That’s it! Your AI Agent is now configured to use the Redpanda UI Registry via the shadcn MCP and best practices.

Last updated on

Was this page helpful?