Magic MCP → 21st MCP (compatibility proxy)

What it is – A tiny npm package (@21st-dev/magic-mcp) that acts as a drop‑in replacement for the old Magic MCP server. It simply forwards every MCP (Multi‑Component Protocol) request to the new 21st MCP service, letting legacy configurations keep working while you migrate to the newer 21st CLI.

---

How it works

• The package is a stdio proxy: you run npx @21st-dev/magic@latest API_KEY="…" and it pipes the JSON‑RPC‑like MCP messages to https://21st.dev/api/mcp.
• It accepts the historic ways of supplying the API key (positional argument, --API_KEY=, /API_KEY:, -API_KEY, or the env vars TWENTY_FIRST_API_KEY / API_KEY_21ST).
• The server you talk to is the same one the 21st CLI uses, so all tools you could call before (generate, iterate_generation, search, etc.) are still available, just under the new names.

---

Getting started

# Recommended – install the full 21st MCP via the CLI
npx @21st-dev/cli@latest init --client cursor   # or claude | vscode | windsurf | codex

If you only need the proxy:

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

Or add the server manually to an mcp.json configuration:

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

Note: Old Magic API keys no longer work; generate a fresh one at https://21st.dev/mcp.

---

AI access

• The server only lists the generate and iterate_generation tools when your account has AI generation enabled (get_usage.aiGenerationEnabled).
• Without AI you can still use search, get_component, etc., and run your own coding agent on the returned drafts.
• A call that would require a paid AI subscription returns ai_subscription_required; simply wait until AI is enabled before retrying.

---

Legacy tool name mapping

Legacy Magic tool	21st MCP tool
21st_magic_component_builder	generate
21st_magic_component_inspiration	get_inspiration
21st_magic_component_refiner	generate (refine)
logo_search	search_logo

The proxy automatically translates the old names, so existing agents keep functioning.

---

Using it as a plugin

The repo ships a plugin manifest for several AI‑assistant platforms:

• Claude Code – claude plugin marketplace add 21st-dev/magic-mcp then /plugin install 21st
• Grok Build – grok plugin marketplace add 21st-dev/magic-mcp && grok plugin install 21st --trust
• Cursor – install "21st" from the Cursor Marketplace and set API_KEY_21ST in the plugin settings.

All platforms expect the API key in the API_KEY_21ST environment variable.

---

Where to learn more

• 21st MCP docs & API keys: https://21st.dev/mcp
• 21st CLI npm package: https://www.npmjs.com/package/@21st-dev/cli
• Marketplace listings: Cursor, Grok, Claude (links in the README).

---

TL;DR

@21st-dev/magic-mcp is a thin compatibility shim that lets old Magic‑MCP configurations talk to the new 21st MCP service. Install it (or the full 21st CLI), supply a fresh API key, and your existing tools and agents keep working with the updated backend.