> ## Documentation Index
> Fetch the complete documentation index at: https://magica.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Connect Claude Code, Claude Desktop, or Cursor to the Magica MCP server.

Setup takes under a minute. Grab your API key, paste it into your client's config, and start asking your assistant to run workflows.

***

## 1. Get your API key

Open [app.magica.com](https://app.magica.com), then **Settings → API Keys → Manage** to create or copy a key. This is the same Bearer token used for the REST API.

<Card title="Step-by-step API key walkthrough" icon="key" href="/authentication" horizontal>
  See the full Authentication page for click-by-click screenshots, rate limits,
  key rotation, and revocation.
</Card>

<Tip>
  Treat the key like a password — store it in your password manager or a `.env`
  file, never in committed code.
</Tip>

***

## 2. Connect your client

Pick your assistant below. Replace `YOUR_API_KEY` with the key from step 1.

<Tabs>
  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the MCP server via CLI">
        Run this in your terminal:

        ```bash theme={null}
        claude mcp add --transport http magica https://api.magica.com/api/mcp \
          --header "Authorization: Bearer YOUR_API_KEY"
        ```
      </Step>

      <Step title="Verify the server is registered">
        ```bash theme={null}
        claude mcp list
        ```

        You should see `magica` in the output.

        <Frame caption="`claude mcp list` showing the Magica server registered">
          <img className="block dark:hidden" src="https://mintcdn.com/galaxyai-f8150d75/DBhRDarFZNKVqMQi/logo/logo_light_theme.svg?fit=max&auto=format&n=DBhRDarFZNKVqMQi&q=85&s=6f2c433ff16ffb278918ac9ebdf0de20" alt="Terminal output of claude mcp list with magica visible" width="1474" height="411" data-path="logo/logo_light_theme.svg" />

          <img className="hidden dark:block" src="https://mintcdn.com/galaxyai-f8150d75/DBhRDarFZNKVqMQi/logo/logo_dark_theme.svg?fit=max&auto=format&n=DBhRDarFZNKVqMQi&q=85&s=12e176141e9a0793a64292bb91603779" alt="Terminal output of claude mcp list with magica visible" width="1474" height="411" data-path="logo/logo_dark_theme.svg" />
        </Frame>
      </Step>

      <Step title="Start using tools">
        Open a new Claude Code session and ask it to list your workflows or start a run.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop">
    <Tabs>
      <Tab title="Connector">
        <Steps>
          <Step title="Open Claude settings">
            Launch the app or open [claude.ai](https://claude.ai) and go to **Settings → Connectors**.

            <Frame caption="Claude Desktop — Settings → Connectors">
              <img className="block dark:hidden" src="https://mintcdn.com/galaxyai-f8150d75/DBhRDarFZNKVqMQi/logo/logo_light_theme.svg?fit=max&auto=format&n=DBhRDarFZNKVqMQi&q=85&s=6f2c433ff16ffb278918ac9ebdf0de20" alt="Claude Desktop settings sidebar with Connectors selected" width="1474" height="411" data-path="logo/logo_light_theme.svg" />

              <img className="hidden dark:block" src="https://mintcdn.com/galaxyai-f8150d75/DBhRDarFZNKVqMQi/logo/logo_dark_theme.svg?fit=max&auto=format&n=DBhRDarFZNKVqMQi&q=85&s=12e176141e9a0793a64292bb91603779" alt="Claude Desktop settings sidebar with Connectors selected" width="1474" height="411" data-path="logo/logo_dark_theme.svg" />
            </Frame>
          </Step>

          <Step title="Add a custom connector">
            Click **Add custom connector**, name it `Magica`, and paste the URL:

            ```
            https://api.magica.com/api/mcp
            ```

            <Frame caption="Add custom connector dialog">
              <img className="block dark:hidden" src="https://mintcdn.com/galaxyai-f8150d75/DBhRDarFZNKVqMQi/logo/logo_light_theme.svg?fit=max&auto=format&n=DBhRDarFZNKVqMQi&q=85&s=6f2c433ff16ffb278918ac9ebdf0de20" alt="Claude Desktop dialog to add a custom MCP connector" width="1474" height="411" data-path="logo/logo_light_theme.svg" />

              <img className="hidden dark:block" src="https://mintcdn.com/galaxyai-f8150d75/DBhRDarFZNKVqMQi/logo/logo_dark_theme.svg?fit=max&auto=format&n=DBhRDarFZNKVqMQi&q=85&s=12e176141e9a0793a64292bb91603779" alt="Claude Desktop dialog to add a custom MCP connector" width="1474" height="411" data-path="logo/logo_dark_theme.svg" />
            </Frame>
          </Step>

          <Step title="Connect and sign in">
            Click **Add → Connect**, then authenticate with your Magica Auth. You're all set — ask Claude to list or run a workflow.
          </Step>
        </Steps>
      </Tab>

      <Tab title="JSON config">
        Edit your `claude_desktop_config.json`:

        * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
        * Windows: `%APPDATA%\Claude\claude_desktop_config.json`

        ```json theme={null}
        {
          "mcpServers": {
            "magica-workflow": {
              "command": "npx",
              "args": [
                "mcp-remote",
                "https://api.magica.com/api/mcp",
                "--header",
                "Authorization: Bearer YOUR_API_KEY"
              ]
            }
          }
        }
        ```

        Restart Claude Desktop and the Magica tools will appear in the tool picker.
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Codex">
    <Steps>
      <Step title="Add the MCP server via CLI">
        Run this in your terminal:

        ```bash theme={null}
        codex mcp add magica --url https://api.buildfast.club/api/mcp
        ```
      </Step>

      <Step title="Authenticate">
        On first use, Codex will prompt you to provide your Magica API key. Paste the `gx_…` token from [app.magica.com](https://app.magica.com).
      </Step>

      <Step title="Start using tools">
        Open a new Codex session and ask it to list your workflows or start a run.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):

    ```json theme={null}
    {
      "mcpServers": {
        "magica": {
          "url": "https://api.magica.com/api/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

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

    <Frame caption="Cursor — Magica tools available in the chat tool picker">
      <img className="block dark:hidden" src="https://mintcdn.com/galaxyai-f8150d75/DBhRDarFZNKVqMQi/logo/logo_light_theme.svg?fit=max&auto=format&n=DBhRDarFZNKVqMQi&q=85&s=6f2c433ff16ffb278918ac9ebdf0de20" alt="Cursor IDE chat showing the Magica MCP tools in the tool picker" width="1474" height="411" data-path="logo/logo_light_theme.svg" />

      <img className="hidden dark:block" src="https://mintcdn.com/galaxyai-f8150d75/DBhRDarFZNKVqMQi/logo/logo_dark_theme.svg?fit=max&auto=format&n=DBhRDarFZNKVqMQi&q=85&s=12e176141e9a0793a64292bb91603779" alt="Cursor IDE chat showing the Magica MCP tools in the tool picker" width="1474" height="411" data-path="logo/logo_dark_theme.svg" />
    </Frame>
  </Tab>
</Tabs>

<Tip>
  If you're using **Claude Code** or **Codex**, prefer the CLI install — it's
  faster and avoids hand-editing JSON.
</Tip>

***

## 3. Start using tools

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

* *"List my workflows."*
* *"Build a workflow that takes a prompt and generates an image with Flux 2 Pro."*
* *"Run the Nano Banana Pro model on this image and add a dog to the scene."*

See [Available Tools](/mcp-server/tools) for the full list.