MCP Client Integrations

Purpose and Scope

This guide explains how to connect the shadcn MCP server to common coding-agent clients while keeping the setup registry-aware. MCP, or Model Context Protocol, lets an AI client ask a local server for project and registry capabilities. In shadcn/ui, the registry side is the important shared contract: the MCP server can browse and install from any shadcn-compatible registry as long as the registry exposes a valid root catalog and item payloads. For teams, this means the same private design system, public GitHub registry, or indexed community registry can be made discoverable to Claude Code, Cursor, VS Code, Codex, and similar clients.

Sources: apps/v4/content/docs/registry/github.mdx, apps/v4/content/docs/changelog/2025-02-registry-schema.mdx, apps/v4/content/docs/changelog/2025-07-universal-registry.mdx

The client-specific commands are intentionally small because the registry model does most of the work. A registry author publishes reusable files; a project records custom registry namespaces in components.json; then the MCP client is initialized for the editor or agent environment. The official MCP docs describe this sequence for Claude Code, Cursor, VS Code, Codex, and OpenCode: configure a namespace such as @acme, run npx shadcn@latest mcp init --client <client>, restart the client, and ask the agent to browse or compose from that registry. The source-backed registry docs explain why that works across more than React components: registry items can represent components, hooks, configs, docs, templates, workflows, rules, and MCP configuration files.

Relevant Source Files

• apps/v4/content/docs/registry/github.mdx — documents public GitHub repositories as source registries, the owner/repo/item install form, registry requirements, and examples that explicitly include MCP configuration files such as .mcp.json and .cursor/mcp.json.
• apps/v4/content/docs/changelog/2025-02-registry-schema.mdx — records the registry schema direction: flat JSON distribution through the CLI, custom styles, hooks, animations, Tailwind layers, utilities, and third-party registry composition.
• apps/v4/content/docs/changelog/2025-07-universal-registry.mdx — introduces universal registry items that can be distributed to any project without requiring React, Tailwind, a framework, or components.json.
• apps/v4/content/docs/changelog/2025-09-registry-index.mdx — explains the open registry index, npx shadcn add @ai-elements/prompt-input, and automatic addition of indexed registries to components.json.
• apps/v4/content/docs/changelog/2025-10-registry-directory.mdx — announces the Registry Directory as a browsable list of code registries built into the CLI with no configuration required.
• apps/v4/content/docs/changelog/2026-05-registry-include.mdx — documents include, shadcn registry validate, shadcn build, and registry loaders used to organize, validate, and serve larger source registries.

Registry-Aware Configuration Model

A registry-aware MCP setup starts with addressability. For a custom hosted registry, consumers normally add a namespace to components.json, for example @acme mapped to https://acme.com/r/{name}.json. The MCP server can then ask for the registry index and resolve namespaced items consistently with CLI installation. For a public GitHub registry, the source file states that any public GitHub repository can become a registry by adding registry.json at the repository root, after which users can install with npx shadcn@latest add <username>/<repo>/<item>. That path is useful for MCP because the repository itself becomes the source registry; no separate registry server or generated JSON publishing step is required.

Sources: apps/v4/content/docs/registry/github.mdx

The compatibility boundary is the registry schema, not the UI framework. The February schema update describes distributing code as a flat JSON file through the CLI and calls out custom styles, design-system tokens, components, CSS variables, hooks, animations, and Tailwind layers. The July universal registry update goes further by allowing items that can be installed into any code project without React, Tailwind, framework assumptions, or even components.json. For MCP clients, this broadens the agent workflow: the model can ask for a design-system component, a lint rule, an AGENTS.md, a migration script, or a documentation convention as long as the registry item describes the files using valid registry metadata.

Sources: apps/v4/content/docs/changelog/2025-02-registry-schema.mdx, apps/v4/content/docs/changelog/2025-07-universal-registry.mdx

Client Setup Flow

Use the same project-local sequence for each supported client. First, make sure the registry exists and exposes a root registry.json or equivalent registry endpoint. Second, configure any custom namespaces in components.json if the registry is not being discovered through the public registry index or directory. Third, initialize the MCP client integration from the project root. The official setup examples use npx shadcn@latest mcp init --client claude for Claude Code, npx shadcn@latest mcp init --client cursor for Cursor, and the same command shape with --client vscode or --client codex for VS Code and Codex. Finally, restart the client so it reloads its MCP configuration.

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

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

After initialization, test with prompts that exercise registry discovery before asking for a larger implementation. The official docs suggest prompts such as “Show me the components in the acme registry” and “Create a landing page using items from the acme registry.” Claude Code also exposes an /mcp command for debugging the server connection. If the client can list registry items, move on to installation or composition prompts. If it cannot, verify that the root registry file is reachable, the namespace URL includes the {name} placeholder where required, and the registry payload conforms to the registry and registry-item schemas.

Discovery Through Indexes, Directories, and GitHub

Not every integration needs manual namespace setup. The September registry index changelog says users can search, view, and add items from an open source registry index without configuring components.json; when an indexed item is installed, the registry is added to components.json automatically. The October registry directory changelog describes a browsable directory of code registries that is built into the CLI with no config required. In an MCP workflow, these features matter because an agent can start from known public registries instead of relying on every project to predeclare each namespace. Manual namespace configuration is still the right fit for private, authenticated, unpublished, or team-specific registries.

Sources: apps/v4/content/docs/changelog/2025-09-registry-index.mdx, apps/v4/content/docs/changelog/2025-10-registry-directory.mdx

GitHub registries are the lightest-weight source registry path for public code. The GitHub registry documentation says the repository must be public, live on github.com, have a root registry.json, use valid schemas, and reference source files that exist in the repository. It also says private repositories and GitHub Enterprise hosts are not supported by GitHub addresses; protected registries should instead use namespaces and authentication. This distinction is important for AI clients: a public owner/repo/item address is convenient for open examples, while organization-internal registries should be configured as explicit namespace URLs with whatever authentication flow the registry supports.

Sources: apps/v4/content/docs/registry/github.mdx

Reference: Client and Registry Contracts

Large registries should be maintained as source artifacts instead of hand-edited monoliths. The May 2026 registry update adds include so a root registry.json can compose nested registry files, and it adds shadcn registry validate to check the root registry, included files, item schemas, duplicate names, include rules, and local item paths before publishing. The same update explains that shadcn build resolves included registries into a flattened output and preserves item file paths relative to the root. For MCP client reliability, validation is the practical preflight: agents work best when registry discovery fails early for authors rather than during an interactive coding session.

Sources: apps/v4/content/docs/changelog/2026-05-registry-include.mdx

Next Steps

For a new integration, start with one client and one registry namespace before expanding to the whole team. Add the namespace to components.json, run the matching mcp init command, restart the client, and ask it to list registry items. If the registry is public and reusable outside your organization, consider adding it to the registry index or directory so users and agents can discover it with less setup. If the registry is large, split it with include and run npx shadcn registry validate as part of your publishing workflow. Read the registry overview, registry index, registry authentication, and MCP troubleshooting pages next when you need deeper coverage of discovery, protected endpoints, or client debugging.