Setup

Setup takes under a minute. Claude Desktop connects with OAuth; clients that support custom headers can use a Magica API key as either an Authorization Bearer token or an x-api-key header.

1. Choose your authentication method

For Claude Desktop, skip the API-key step. Its remote connector UI uses OAuth and does not require you to paste a token, client ID, or client secret. For Claude Code, Cursor, or another client that supports custom headers, open magica.com, then Settings → API Keys → Manage to create or copy a key. This is the same Bearer token used for the REST API.

Step-by-step API key walkthrough

See the full Authentication page for click-by-click screenshots, rate limits, key rotation, and revocation.

If you use an API key, treat it like a password — store it in your password manager or a .env file, never in committed code.

2. Connect your client

Pick your assistant below. Where a command shows YOUR_API_KEY, replace it with the key from step 1.

Claude Code
Claude Desktop
Codex
Cursor

Add the MCP server via CLI

Run this in your terminal:

claude mcp add --transport http magica https://inference.magica.com/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Verify the server is registered

claude mcp list

You should see magica in the output.

claude mcp list showing the Magica server registered

Start using tools

Open a new Claude Code session and ask it to find an image model or start a generation.

Open Claude settings

Launch the app or open claude.ai and go to Settings → Connectors.

Claude Desktop — Settings → Connectors

Add a custom connector

Click Add custom connector, name it Magica, and paste the URL:

https://inference.magica.com/v1/mcp

Choose these options when Claude displays them:

Setting	Selection
Authentication	Always required
OAuth client	No client ID — register one automatically
Additional request headers	Leave empty
Advanced → Transport	Streamable HTTP

Magica supports automatic OAuth client registration (DCR). The Use Anthropic’s hosted client metadata option (CIMD) is not supported; select No client ID — register one automatically even if Claude recommends hosted client metadata. You do not need to supply an OAuth client ID, client secret, or API key.In older Claude versions that show only OAuth Client ID and OAuth Client Secret, leave both fields empty.

Add custom connector dialog

Connect and sign in

Click Add → Connect, sign in to Magica, and approve the requested access. Return to Claude and enable Magica in the conversation’s connectors menu. Ask Claude to list available image models to check the connection before generating media.If Claude says “Couldn’t register with Magica’s sign-in service”, edit the connector and select automatic registration as described above, then reconnect. If your Claude version cannot edit these options, remove the failed connector and add it again with these settings.For “Couldn’t reach Magica” or “Connection issue”, check the URL above and the Streamable HTTP transport. If the error persists, send support the error reference, Claude version, and time of the attempt. Keep passwords, API keys, and OAuth tokens out of screenshots.

Add the MCP server via CLI

Run this in your terminal:

codex mcp add magica --url https://inference.magica.com/v1/mcp

Authenticate

On first use, Codex will prompt you to provide your Magica API key. Paste the gx_… token from magica.com.

Start using tools

Open a new Codex session and ask it to find a model or start a generation.

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "magica": {
      "url": "https://inference.magica.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Restart Cursor — the Magica tools appear in the chat tool picker.

Cursor — Magica tools available in the chat tool picker

Current Claude Desktop releases add remote MCP servers through Settings → Connectors. Do not put this remote connector in claude_desktop_config.json; that file is for local desktop extensions.

3. Start using tools

Your AI assistant now has access to the Magica MCP tools. Try one of these prompts:

“Show me the available text-to-image models.”
“Generate a product photo of a red sneaker on a studio backdrop.”
“Run the Nano Banana Pro model on this image and add a dog to the scene.”

See Available Tools for the full list.

Get Started

Guides

Reference

1. Choose your authentication method

Step-by-step API key walkthrough

2. Connect your client

3. Start using tools