21st MCP (formerly Magic MCP)

The recommended way to install the 21st MCP (formerly Magic MCP) for AI agents is using the @21st-dev/cli. Use the init command with the --client flag to specify your environment (e.g., cursor, claude, vscode, windsurf, or codex).

npx @21st-dev/cli@latest init --client <cursor|claude|vscode|windsurf|codex>

The @21st-dev/magic package acts as a thin stdio proxy that forwards messages to the unified 21st MCP server. This allows existing mcp.json configurations to continue working. The API key can be provided in several formats:

• Positional: API_KEY="..."
• Flag: --API_KEY=...
• Slash: /API_KEY:...
• Dash: -API_KEY ...
• Environment Variables: TWENTY_FIRST_API_KEY or API_KEY_21ST

For clients that only support stdio servers, you can use the @21st-dev/magic compatibility proxy. Set the API_KEY_21ST environment variable with your 21st API key.

{
  "mcpServers": {
    "21st": {
      "command": "npx",
      "args": ["-y", "@21st-dev/magic@latest"],
      "env": { "API_KEY_21ST": "YOUR_21ST_API_KEY" }
    }
  }
}

Since the 21st MCP is a plain HTTP MCP server, you can add it manually to your MCP configuration. You will need an API key from 21.dev/mcp.

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

If your MCP client supports HTTP servers, you can add the 21st MCP manually by pointing to the remote URL and providing your API key in the headers using the x-api-key key.

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

The @21st-dev/magic package acts as a stdio-to-HTTP proxy that forwards MCP messages to the unified 21st MCP endpoint. This is primarily used to maintain compatibility with older agent configurations that expect the legacy Magic tool names.

To run the shim, provide your API key using one of the supported formats (see API Key Resolution).

The 21st MCP supports legacy Magic tool names for backward compatibility, but it is recommended to use the new tool names. Use tools/list to see the full current set of available tools.

| Legacy Magic tool | 21st MCP tool |
| --- | --- |
| `21st_magic_component_builder` | `generate` |
| `21st_magic_component_inspiration` | `get_inspiration` |
| `21st_magic_component_refiner` | `generate` (new generation from the refinement prompt) |
| `logo_search` | `search_logo` (one query per call) |

The shim resolves the API key from several command-line argument patterns and environment variables. It checks them in the following order:

Command Line Arguments:

• API_KEY=value (positional)
• --API_KEY=value
• /API_KEY:value (Windows style)
• -API_KEY=value
• -API_KEY value (separate arguments)

Environment Variables:

1. TWENTY_FIRST_API_KEY
2. API_KEY_21ST
3. API_KEY

The shim maintains compatibility for agents using old Magic tool names. The following tools are still callable through the proxy:

• 21st_magic_component_builder
• 21st_magic_component_inspiration
• 21st_magic_component_refiner
• logo_search