Magic MCP Is Now a Compatibility Proxy: Installing the 21st MCP in Claude Code and Cursor

The package you installed is no longer the server you are talking to

The README states the situation plainly: the Magic MCP server (@21st-dev/magic) has been replaced by the unified 21st MCP, installed through the 21st CLI, with setup at 21st.dev/mcp. The npm package still exists, but since v0.2.0 it is a small stdio proxy that forwards every MCP message to the 21st MCP server. The binary is still named magic and still points at dist/index.js.

That distinction matters when you debug. If an agent tool call behaves differently than it did last year, the proxy is not the thing that changed. The server behind it is, and the README says the proxy forwards discovery to the server, so even an un-updated proxy version receives new server behavior without an npm update. Your client's tool list is a view of a remote server, not of the package on disk.

The audience here is narrow and specific: teams with working mcp.json entries that reference @21st-dev/magic and no appetite for a config migration right now. Everyone else is pointed at the 21st CLI.

What the proxy actually forwards, and what changed in the tool names

The mechanism is a stdio MCP server that relays messages. Your editor launches the process, the process talks to https://21st.dev/api/mcp on your behalf, and the tools you see are the ones available to the authenticated account. Nothing about component search or generation happens locally.

Because the surface moved, the names moved too. The README gives a mapping table: 21st_magic_component_builder becomes generate, 21st_magic_component_inspiration becomes get_inspiration, 21st_magic_component_refiner becomes generate as a new generation from the refinement prompt, and logo_search becomes search_logo with one query per call. The server still accepts the legacy names and translates them, which is why agents that memorized the old tools keep working. The README asks you to prefer the new names.

One consequence of the mapping is easy to miss. Two legacy tools collapse into one new tool, so anything that keyed off the refiner as a distinct capability now needs to express that intent in the prompt instead. The README also notes that the current server exposes considerably more than the old four tools: catalog search across components, themes and templates, paid code retrieval, bookmarks, team libraries, UI generation with variants, and profile management. It does not enumerate the full list, and says to connect and call tools/list to see what your account has. Treat any tool inventory you find in a blog post as a guess.

Installing Magic MCP and running a first search from Claude Code

Two paths exist. The README recommends the 21st CLI, and keeps the proxy alive for old configs. Start with the recommended one if you are setting up fresh. The init command takes a client name, and the README lists cursor, claude, vscode, windsurf and codex as the accepted values.

npx @21st-dev/cli@latest init --client cursor

Run it, then open the MCP configuration your client generated and confirm the server entry is present. The second path is the manual one, and the README gives the shape of it: the 21st MCP is a plain HTTP MCP server, so the entry is a URL plus a header, not a command.

{
  "mcpServers": {
    "21st": {
      "url": "https://21st.dev/api/mcp",
      "headers": { "x-api-key": "YOUR_21ST_API_KEY" }
    }
  }
}

Get the key at 21st.dev/mcp. If you are keeping an existing @21st-dev/magic entry instead, the README says the invocation still works, and that the key is accepted in all the historical forms: positional API_KEY="...", --API_KEY=..., /API_KEY:..., -API_KEY ..., or the TWENTY_FIRST_API_KEY and API_KEY_21ST environment variables.

npx -y @21st-dev/magic@latest API_KEY="..."

For a first real use, ask the agent to search 21st for a component rather than reaching for a slash command. The README is explicit that the old /ui and /21 trigger phrases were a convention of the legacy tool descriptions, not part of the protocol, and that natural language is the way to invoke search or generate. A reasonable first call is a search for a specific component type, followed by get_component on a result you like, then adapting the returned code with your own agent. If generation is enabled, ask for a variant instead. Node 18.0.0 or newer is required according to package.json.

The API key reset is the failure mode that will catch most people

The README states that old Magic API keys were reset, and that keys issued by the old Magic console no longer work anywhere. This is not a deprecation warning with a grace period. A config that has been untouched for a year will start failing, and the failure will look like an authentication problem inside a tool call rather than an obvious config error.

The second failure mode is quieter. Builder component access does not enable hosted 21st AI. The server lists generate and iterate_generation only when AI access is enabled, so an account without it sees a tool list that simply lacks them. The README points at get_usage.aiGenerationEnabled as the check, and adds a caveat worth repeating: that field reports access, not the remaining AI credit balance. A cached or legacy generation call can return ai_subscription_required, and the README says not to retry until AI is enabled. After enabling it, refresh the client tool list or reconnect.

The fallback is documented rather than implied. With AI off, use search and get_component and adapt the code with your own coding agent. The README also notes that existing drafts remain readable. If your workflow depends on the server generating UI for you, this package is the wrong tool until that access is turned on.

How the agent plugin route differs from the MCP server route

The repository is also packaged as an agent plugin, and the README makes a point that is unusual: you do not wait for a store, because the repo is itself a marketplace and can be added directly. The plugin bundles an MCP server plus a UI skill, which is a different distribution shape from a bare MCP entry. The plugin config expects the API key in the API_KEY_21ST variable in every client.

claude plugin marketplace add 21st-dev/magic-mcp

The README shows the same pattern for Grok Build and Codex CLI, and mentions store listings for Cursor and Grok Bot, plus a .claude-plugin/ manifest in the repo that allows loading locally with claude --plugin-dir . The practical difference is that a plugin can carry a skill alongside the server, so the agent gets UI guidance rather than only tool definitions. If you only need component search inside an existing MCP setup, the plain HTTP entry is the smaller change.

A comparison worth making: a conventional MCP server such as a local filesystem or database server runs the logic on your machine and ships its own code. This one is a client for a hosted service. Everything about availability, authentication and tool inventory is decided remotely, which is why the package version and the registry version are independent. The README says server.json mirrors the official dev.21st/mcp registry listing, and that the registry version is independent of this compatibility package version.

Licence and the cost of keeping an old config alive

The package is ISC licensed, which is a permissive licence, and package.json is the source for that. The repository also carries a Dockerfile based on node:22.14.0-alpine that installs dependencies, runs the TypeScript build and starts node dist/index.js, with the command noted as coming from smithery.yaml. Nothing in the licence text is unusual for an npm CLI wrapper, but the licence covers this proxy, not the hosted service it talks to. Terms for the 21st MCP server, API keys and paid code retrieval come from 21st.dev, and the README does not restate them. Treat the two as separate questions.

The upgrade cost is the interesting part. The compatibility proxy is deliberately thin, and the README says existing proxy versions receive server-side behavior changes without an npm update. That cuts both ways. You get new server tools for free, and you also get new server behavior without a version bump you can pin to. The only upgrade that forces action is the key reset, and the README's recommendation is to switch to npx @21st-dev/cli@latest init rather than stay on the proxy. There is no documented rollback path in the README if a server-side change breaks your agent's assumptions, and no documented version pinning for the remote side.

Editorial conclusion

Adopt it if you already have an @21st-dev/magic entry in mcp.json and want it to keep working without editing client config; the proxy exists for exactly that. Do not adopt it for a new setup, and do not expect the old four tools to be the whole surface: the README says the current server exposes catalog search, paid code retrieval, bookmarks, team libraries and UI generation, and tells you to call tools/list to see what your account has. Before you rely on generation, verify two things: that get_usage.aiGenerationEnabled reports true, because the server only lists generate and iterate_generation when AI access is enabled, and that your key came from 21st.dev/mcp rather than the old Magic console.

Frequently asked questions

Official sources

1. 21st-dev/magic-mcp on GitHub
2. License: ISC
3. Project website
4. README
5. Releases