Magic MCP Is Now a Proxy: What @21st-dev/magic Still Does for Existing Cursor and Claude Code Configs

The problem: a renamed backend and a dead key format

Magic MCP used to be its own server at magic.21st.dev. The README states that backend was superseded by a unified 21st MCP, and that all keys issued by the old Magic console were reset for security. That combination is the worst kind of breakage for an editor plugin: the config file still looks valid, the process still starts, and the failure surfaces later as an authentication error or a missing tool. This package exists to soften the second half of that problem. It is published so that existing mcp.json entries referencing @21st-dev/magic keep functioning, but they now talk to the same server as the 21st CLI, scoped to whatever the authenticated account can reach. The audience is narrow and specific: teams with committed or shared MCP configs they do not want to rewrite, and agents whose tool descriptions still remember the old Magic names. If you are configuring a client for the first time, this package is not for you.

How the proxy works: stdio in, HTTP out

Since v0.2.0 the package is a small stdio proxy. It accepts MCP messages on standard input and forwards every one of them to the 21st MCP server, which the README describes as a plain HTTP MCP server at https://21st.dev/api/mcp. The practical consequence is that the proxy holds no component catalog and no generation logic of its own. Tool discovery is forwarded too, which the README calls out explicitly: existing proxy versions receive server-side changes without an npm update. That is a real architectural benefit, because it means a new tool appearing on the 21st side shows up in your client without you touching package.json. The cost is that the proxy cannot fix anything the server decides. If the server withholds a tool from your account, the proxy faithfully reports the shorter list. The API 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. That tolerance is the whole point of the package. It means a config written against the old argument style does not need to be rewritten to keep authenticating.

Running it: the two commands that matter

The legacy invocation still works as documented: npx -y @21st-dev/magic@latest API_KEY="...". That is the path for an unchanged config. The recommended path is the 21st CLI, which writes the client config for you: npx @21st-dev/cli@latest init --client cursor, with claude, vscode, windsurf and codex as the other accepted values. Manual setup is a URL and a header, not a command: a mcpServers entry named 21st with url https://21st.dev/api/mcp and headers containing x-api-key set to your key. Keys come from 21st.dev/mcp. There is also a plugin route that does not go through a store. The repository is itself a marketplace listing, so Claude Code users can run claude plugin marketplace add 21st-dev/magic-mcp and then /plugin install 21st; Codex CLI users run codex plugin marketplace add 21st-dev/magic-mcp and install 21st from /plugins; Grok Build uses grok plugin marketplace add 21st-dev/magic-mcp followed by grok plugin install 21st --trust. In every client the plugin config expects the key in the API_KEY_21ST variable, which is a different name from the ones the proxy accepts. That inconsistency between the proxy's environment variables and the plugin's is worth knowing before you copy a snippet between the two setups.

Tool names: translation is not the same as equivalence

The server still accepts legacy Magic tool names and translates them, so an agent that remembers 21st_magic_component_builder keeps working. The mapping is documented: 21st_magic_component_builder becomes generate, 21st_magic_component_inspiration becomes get_inspiration, logo_search becomes search_logo with one query per call, and 21st_magic_component_refiner also becomes generate, described as a new generation from the refinement prompt. That last row is the interesting one. A refiner and a generator are not the same operation, and collapsing them means the refinement call is re-expressed as a fresh generation rather than an edit to an existing artifact. Whether that produces the same result is not something the README claims, and I cannot confirm it from the material. Treat the alias table as a compatibility shim for old prompts, not as evidence that the old four-tool mental model still describes the server. The README says the current server exposes catalog search across components, themes and templates, paid code retrieval, bookmarks, team libraries, UI generation with variants, and profile management. The old names cover a fraction of that surface.

AI generation is gated separately from component access

This is the limitation most likely to waste an afternoon. Builder component access does not enable hosted 21st AI. The server lists the generate and iterate_generation tools only when AI access is enabled, which means a working, authenticated connection can still hand your agent a tool list without generation in it. The check is get_usage.aiGenerationEnabled, and the README is careful about what that field means: it reports access, not the remaining AI credit balance. So a true value tells you the tools should be available, not that a call will succeed. A cached or legacy generation call can return ai_subscription_required, and the README's instruction is explicit: do not retry until AI is enabled. After enabling it, refresh the client tool list or reconnect, because the proxy forwards discovery and will not push an updated list on its own. The fallback with AI off is manual: use search and get_component, then adapt the returned code with your own coding agent. Existing drafts remain readable. If your workflow depends on hosted generation and you have not confirmed AI access on your account, this package will look broken when it is merely unentitled.

Where the compatibility layer stops being the right tool

The proxy is a migration aid, and the README says so: it recommends switching to npx @21st-dev/cli@latest init. Every release of this package is a release of a forwarder, so its version number tells you nothing about the server behind it. The README states plainly that the registry version in server.json is independent of the compatibility package version, and that server.json mirrors the official dev.21st/mcp registry listing. If you are debugging a missing tool or a generation failure, the package version is not a useful signal. The other boundary is the trigger-phrase convention. The old /ui and /21 phrases were part of the legacy tools' descriptions, not part of the protocol, and the README's answer is to use natural language instead: ask the agent to search 21st for components, or use hosted generation when AI is enabled. Anyone whose team documentation still instructs people to type /ui is maintaining a convention that the protocol never guaranteed. That is a documentation cost, not a code cost, but it is the kind of thing that lingers for months after the underlying change.

The real alternative is the same server without the wrapper

The difference between this package and the 21st CLI is not features. Both end up talking to https://21st.dev/api/mcp with the same key and the same account-scoped tool list. The difference is configuration surface. The CLI writes client config for a named client and gives you a direct HTTP MCP entry; the proxy keeps a stdio process in the middle so that an argument style like -API_KEY ... or an environment variable like TWENTY_FIRST_API_KEY continues to resolve. If your config is generated, checked into a repository, or shared across a team that has not all upgraded, the proxy buys you time. If your config is a single file you can edit, the proxy adds a process, a version number that does not track the server, and a second naming scheme for the API key. The plugin route is a third option and is genuinely different in shape: it ships an MCP server plus a UI skill, and it is installed through each client's own plugin marketplace command rather than by writing JSON. That is a different distribution mechanism, not a different backend.

Licence and the cost of staying on a proxy

The package is ISC licensed, which is permissive and short; it places few obligations on how you redistribute or embed the code. That covers this repository, not the hosted service behind it. Nothing in the supplied material describes the terms of the 21st MCP API, what a paid code retrieval or a generation call costs, or what happens to your account if a key is rotated again. The maintenance cost of the proxy itself is low by design, since discovery is forwarded and no catalog is bundled, but the upgrade cost is deferred rather than avoided: you still have to obtain a new key from 21st.dev/mcp, you still have to enable AI access if you want generation tools, and you still have to reconnect clients so the tool list refreshes. The one thing the proxy genuinely saves you is editing config files. Whether that is worth a permanent extra hop depends on how many of those files you have and who owns them.

Editorial conclusion

Keep @21st-dev/magic only if you have an existing mcp.json entry pointing at it and you cannot edit that file yet; anyone starting fresh should run npx @21st-dev/cli@latest init --client cursor (or claude, vscode, windsurf, codex) and skip the proxy entirely. Before adopting either path, verify three things: that your old Magic key has been replaced with one from 21st.dev/mcp, that get_usage.aiGenerationEnabled returns true if you expect the generate and iterate_generation tools to appear in tools/list, and that your client reconnects after AI is enabled so the tool list refreshes.

Official sources

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