MCP Server

Core Idea

The shadcn MCP server lets AI assistants (Claude Code, Cursor, VS Code/Copilot, Codex, OpenCode) browse, search and install items from any shadcn-compatible registry using natural language, instead of manual CLI commands.

Key Concepts

• MCP (Model Context Protocol): Open protocol letting AI assistants securely connect to external tools/data sources; here it bridges the assistant, registries, and the shadcn CLI.
• npx shadcn@latest mcp init --client <name>: One-command setup per client (claude, cursor, vscode, codex, opencode); Codex still requires manual edits to ~/.codex/config.toml since the CLI can't write it.
• .mcp.json: Project-level config file (Claude Code) registering the shadcn MCP server: {"mcpServers": {"shadcn": {"command": "npx", "args": ["shadcn@latest", "mcp"]}}}.
• components.json#registries: Where custom/private registries are configured so the MCP server (and CLI) can reach them, with optional headers for auth.
• Content negotiation via Accept/User-Agent: the CLI sends User-Agent: shadcn and Accept: application/vnd.shadcn.v1+json, application/json;q=0.9, letting a registry serve HTML to browsers and JSON to the MCP/CLI from the same URL.

Code Examples

{
  "mcpServers": {
    "shadcn": { "command": "npx", "args": ["shadcn@latest", "mcp"] }
  }
}

• O que demonstra: configuração mínima do MCP server pro Claude Code.

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

• O que demonstra: como registrar um registry customizado que o MCP server e a CLI vão consumir.

Reference Tables

Client	Setup command	Notes
Claude Code	mcp init --client claude	debug via /mcp
Cursor	mcp init --client cursor	enable in Cursor Settings
VS Code	mcp init --client vscode	Start button in .vscode/mcp.json
Codex	mcp init --client codex	must manually edit ~/.codex/config.toml
OpenCode	mcp init --client opencode	restart after

Anti-patterns

• Expecting Codex config to auto-update: the CLI cannot write ~/.codex/config.toml; add the [mcp_servers.shadcn] block by hand.
• Forgetting env vars for private registries: MCP install fails silently/401s if REGISTRY_TOKEN/API_KEY aren't set in .env.local.

Key Takeaways

1. No config is needed to access the default shadcn/ui registry via MCP; custom registries need components.json#registries.
2. Natural-language prompts like "Build a landing page using components from the acme registry" work once the registry + MCP client are configured.
3. Troubleshooting checklist: verify config → restart client → confirm shadcn is installed → check registry network access; for "No tools or prompts", clear npx cache (npx clear-npx-cache).

Connects To

• registry-mcp (ch103): registry-operator side of MCP support (registry.json requirement, best practices).
• registry-namespace (ch104): @namespace syntax used in MCP prompts to target specific registries.
• registry-authentication (ch102): auth patterns needed for private registries accessed via MCP.