shadcn skill vs MCP server: which one your coding agent needs

shadcn/ui ships two things for coding agents. The first is a skill, listed in the docs as shadcn skills: a set of instructions that teaches the agent how to write shadcn/ui code for your project. The second is an MCP server (MCP is the Model Context Protocol, the standard that lets an AI tool call outside programs), which gives the agent tools for searching and viewing registry items. A registry is a catalogue of components the shadcn CLI can install. We loaded both in Claude Code, counted what each adds to a session, and compared what each returns inside the same app.

Should you install the shadcn skill or the MCP server?

Install the shadcn skill first, and add the shadcn MCP server when your agent can't run shell commands or doesn't load skills. Only the skill reads your project's library, aliases and Tailwind version. In our Base UI project, on shadcn CLI 4.23.0, the CLI commands the skill points to returned the Base UI button file and links to the Base UI dialog docs. The MCP server answered the same requests with Radix dependencies and a Radix example. Keeping both loaded added 292 tokens to an idle Claude Code session. This is a default based on what each one returns: we ran no agent task, so we can't say which writes better UI.

We measured on 11 November 2026 with Claude Code 2.1.322, Claude Opus 5.5 and shadcn CLI 4.23.0, on macOS with Node 24.13.1. The method is under how many tokens each one uses.

What the shadcn skill does

The skill is a folder of Markdown that an agent loads when a task involves shadcn/ui. shadcn released it with CLI v4 on 6 March 2026 (CLI v4 changelog), and it installs with one command:

npx skills add shadcn/ui

Its page on skills.sh showed 143.8K installs when we checked on 11 November 2026.

The skill starts by reading your project. Its main file has a line that runs shadcn info --json and puts the result in front of the agent: framework, Tailwind version, import aliases, icon library, installed components, and which of the two component libraries shadcn/ui supports your project is built on, Base UI or Radix. In our app that output was 3,058 bytes.

The main file, SKILL.md, is 21,606 bytes, and it lists what shadcn calls critical rules. Forms use FieldGroup and Field. Spacing uses gap-*, never space-y-*. A custom trigger uses asChild on Radix and render on Base UI. Twelve more files sit beside it and are read only when a task needs them: six rule files that pair incorrect code with the correct version, a CLI reference, and guides for theming, registries, design systems and the MCP server.

For finding and adding components, the skill sends the agent to the shadcn CLI. search finds an item, view shows its code and add installs it. docs returns links to the documentation, which the agent then fetches, so this path needs web access as well as a shell. In Claude Code the skill pre-approves every shadcn@latest command, add included, for the turn that uses it, so the agent doesn't stop to ask before each one.

An agent decides for itself when to load a skill, and it can skip one. In our earlier test of animation skills, Claude Code left Anthropic's frontend-design skill unloaded in one of three runs.

What the shadcn MCP server does

The MCP server ships inside the shadcn CLI. It arrived with CLI 3.0 on 27 August 2025 (CLI 3.0 changelog), built on the Model Context Protocol. One command writes the config for your editor:

npx shadcn@latest mcp init --client claude

We did not run that command. According to shadcn's MCP docs, the config for Claude Code is a .mcp.json file that starts npx shadcn@latest mcp as a local process.

We started the server from shadcn CLI 4.23.0 and asked it for its tools. There are seven, and we called each one once in our app:

None of the seven installs anything. get_add_command_for_items hands back the CLI command, and the agent, or you, still runs it in a shell.

The server also has no tool for project settings. The skill's own MCP reference says that for aliases, framework and Tailwind version you run shadcn info, because "there is no MCP equivalent".

How many tokens do the shadcn skill and MCP server use in Claude Code?

In Claude Code 2.1.322 with Claude Opus 5.5, the shadcn skill added 166 tokens to an idle session and the shadcn MCP server added 132. We ran the same one-line prompt in four fresh folders and read the prompt size Claude Code reported for each run.

Each folder held a package.json and our components.json. For the skill runs we copied the skill's folder from GitHub into .claude/skills/shadcn, and for the MCP runs the config file started npx shadcn@latest mcp. Every run used this command, with user settings switched off so nothing else on the machine was loaded. Runs without the server passed an empty config file in place of mcp.json:

claude -p "Reply with only the word OK." --model claude-opus-5-5 \
  --output-format stream-json --verbose --setting-sources project \
  --strict-mcp-config --mcp-config mcp.json --no-session-persistence

Prompt tokens are the input, cache-write and cache-read tokens in the result event, added together. Each setup ran once, and the baseline ran twice with the same result. The two rows with the MCP server were measured later the same day than the first two. The MCP server from shadcn 4.21.3 added 170 tokens instead of 132: with that version, Claude Code also listed three tools for reading MCP resources.

Both numbers are small because Claude Code holds most of the content back. For a skill it keeps only the description in context, and the full skill loads when it is invoked (Claude Code skills docs). For MCP servers, tool search is on by default: only tool names load at the start of a session, and a tool's definition loads when the agent goes looking for it (Claude Code MCP docs).

These are the sizes that load on use, counted from the files and outputs:

Added up, the skill should cost about 9,700 tokens the first time a task triggers it: 8,277 plus 1,388. We did not watch it load in a live session. The Claude Code docs say a loaded skill's content stays in context across turns. The MCP server starts smaller and then adds the size of every result. A client that loads all tool definitions up front would carry 1,500 to 1,900 tokens from the first message.

Does the shadcn MCP server work in a Base UI project?

It connects, but in our test it did not return Base UI code. Our app is built on Base UI ("style": "base-nova" in components.json). On shadcn CLI 4.23.0, two of the MCP results described the Radix version of shadcn/ui. A third listed 471 items where the CLI listed 221, and we did not work out why.

We searched for "dialog-demo" because the tool's own description suggests that pattern.

The two libraries don't share an API. Radix swaps a trigger's element with asChild, and Base UI does it with render. An agent that copied the asChild example into a Base UI project would write code for the wrong library. The skill covers that case twice: it reads which library your project uses, and it carries a rule file on the differences. We ran into the same split while building motion for both, and wrote it up in Base UI vs Radix.

We ran the same calls on 4.21.3, the version installed in our repository, and got the same Radix results. Version 4.23.0 came out on 27 October 2026 and moved the server to version 2 of the MCP TypeScript SDK (release notes). The tool output differed in one way. On 4.21.3 the list and search results printed Add command: [object Promise] under every item, and 4.23.0 prints the real command.

When is the MCP server the better choice?

The clearest case is an agent with no shell. A chat client that speaks MCP but can't run commands can still search a registry and read example code through the server. In our run the view tool returned a summary of the component without its file, and you would run the add command it gives you yourself.

The server also suits a setup where you don't want the agent running shell commands at all. The seven tools list, search and view, and none is described as changing files, so you can allow them and keep the shell closed. The skill works the other way, since it pre-approves shadcn commands in Claude Code.

Some agents don't load skills. The skills CLI lists Claude Code, Cursor, Codex, OpenCode and 75 more agents as supported, so check yours before assuming it can't.

Private registries are documented for both. The MCP docs list them as supported, with access tokens set in components.json, and the CLI reads the same file. We only tested the public @shadcn registry.

Keeping both loaded is cheap while idle, and shadcn's skill docs allow for it: they describe component discovery through shadcn docs, shadcn search or the MCP tools. If you run both in a Base UI project, check which library an example targets before your agent copies from it.

Why we removed our own MCP server

We made a smaller version of this choice for Keyframery. On 8 October 2026 we launched a hosted MCP server with four read-only tools. One listed the kinds of change the library animates, two searched and returned docs pages, and one produced a motion theme. A Claude Code plugin shipped it together with a skill.

On 4 November 2026 we removed the server and kept the skill. Everything the docs tools returned was already public as Markdown: every docs page has a .mdx address, and /llms.txt indexes them. The skill tells the agent which page to read, and the agent fetches it like any other URL. With the skill in place, the server no longer gave an agent anything it couldn't already read.

We did give up the theme tool. A motion theme now comes from the theme builder, which copies a prompt for your agent.

The shadcn MCP server is in a different position. It searches registries, which a page of Markdown can't do, so our decision doesn't apply to it. Before adding a server now, we list what it would return and check whether the agent can already read or run the same thing.

What we did not measure

No agent built anything in this test. We counted tokens and compared output, and we ran the CLI commands by hand. The skill never loaded inside a session, so its on-use figures are file sizes we added up. We did not give an agent the same task with each setup, and we can't tell you which one produces better UI.

Each setup ran once, on one client and one model: Claude Code 2.1.322 with Opus 5.5. Token counts change with the model, and other agents load skills and MCP tools in their own ways.

We used one project, a Next.js app on Base UI and Tailwind v4. In a Radix project the MCP results above should match the project's library, though we did not test one. The case for the skill would then rest on project settings alone.

The file sizes in tokens came from sending each file's text to the model once and subtracting an empty run, so they are approximate.

How to install the shadcn skill and MCP server in Claude Code

# The skill
npx skills add shadcn/ui

# The MCP server, for Claude Code
npx shadcn@latest mcp init --client claude

The agent loads the skill on its own when a task involves shadcn/ui in a project with a components.json. It has no slash command to run. According to shadcn's MCP docs, after adding the server you restart Claude Code, run /mcp and look for shadcn marked as connected.

The same docs list cursor, vscode, codex and opencode as other values for --client, and describe one manual config step for Codex. To update later, npx skills update refreshes the skill's files. The server config runs shadcn@latest, so it follows new CLI releases.

The shadcn skill covers how components are composed. Motion and visual design are left to other skills, and we tested four of those on one shadcn/ui app in Best Claude Code skills for UI animation.