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

# Use Mage from Claude, Cursor, and ChatGPT

> Connect Claude, ChatGPT, Claude Code, or Cursor to your Mage account through the Mage MCP server, then ask your assistant to generate images, video, and audio, paid in Gems.

The Mage MCP server connects AI assistants to your Mage account. Once it is connected, you can ask Claude, ChatGPT, Claude Code, or Cursor to pick a model, quote the price, generate an image, video, or audio clip, and bring back the result. It also reads your generation history and saved creations, and uses your saved characters and references.

```text Server URL theme={null}
https://mcp.mage.space/mcp
```

<Note>
  The MCP server is in early access. If connecting fails, write to
  [mage@mage.space](mailto:mage@mage.space).
</Note>

<Warning>
  Every generation your assistant starts is paid in Gems from your account. Your
  assistant can check the price first, and you can disconnect it at any time.
</Warning>

## Connect your assistant

<Tabs>
  <Tab title="Claude">
    Works in Claude on the web, the desktop app, the mobile apps, and Cowork.

    1. In Claude, open **Customize** → **Connectors**, add a custom connector, and paste `https://mcp.mage.space/mcp` as its URL. Select **Add**.
    2. Select **Connect**. A Mage page opens and asks you to sign in if you are not already.
    3. Check that the page names the app you are connecting, then select **Connect**. You return to Claude.
    4. In a chat, turn the Mage connector on from the **+** menu under **Connectors**, and ask for what you want to make.

    On a Team or Enterprise plan, an owner first adds the connector under **Organization settings** → **Connectors**. The Free plan allows one custom connector.
  </Tab>

  <Tab title="ChatGPT">
    Custom connectors need ChatGPT's developer mode, available on paid plans in ChatGPT on the web.

    1. Turn on **Developer mode** in ChatGPT's settings (under **Apps** → **Advanced settings**).
    2. Create a connector with the URL `https://mcp.mage.space/mcp` and OAuth authentication.
    3. Sign in to Mage on the page that opens, check the app's name, and select **Connect**.
    4. Enable the Mage connector in a chat through developer mode.
  </Tab>

  <Tab title="Claude Code">
    Add the server, then sign in from Claude Code:

    ```bash theme={null}
    claude mcp add --transport http mage https://mcp.mage.space/mcp
    ```

    Run `/mcp` in Claude Code, choose **mage**, and authenticate. A browser page opens for you to sign in to Mage and select **Connect**.

    To use an [API key](/api/authentication) instead of signing in:

    ```bash theme={null}
    claude mcp add --transport http mage https://mcp.mage.space/mcp \
      --header "Authorization: Bearer $MAGE_API_KEY"
    ```
  </Tab>

  <Tab title="Cursor">
    [Add Mage to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=mage\&config=eyJ1cmwiOiJodHRwczovL21jcC5tYWdlLnNwYWNlL21jcCJ9) with one click, or add it to `~/.cursor/mcp.json` with an [API key](/api/authentication):

    ```json mcp.json theme={null}
    {
      "mcpServers": {
        "mage": {
          "url": "https://mcp.mage.space/mcp",
          "headers": { "Authorization": "Bearer ${env:MAGE_API_KEY}" }
        }
      }
    }
    ```
  </Tab>
</Tabs>

When an app connects by signing in, Mage shows who is asking before anything is shared: the app's name, the site it comes from, and where you return afterwards. A guest session cannot connect an app; sign in with your Mage account first.

## What your assistant can do

| Tool               | What it does                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------- |
| `list_models`      | Lists the models, with their media type, price in Gems, and what each is for.               |
| `get_model`        | Describes one model: its fields, allowed values, defaults, rules, and price.                |
| `estimate_cost`    | Prices a generation before it starts. Nothing is charged.                                   |
| `generate`         | Starts a generation, paid in Gems.                                                          |
| `get_request`      | Waits for a generation to finish and returns the result link.                               |
| `cancel_request`   | Stops a running generation. Gems are not refunded.                                          |
| `get_account`      | Shows the connected account and its Gems balance.                                           |
| `list_characters`  | Lists your characters and their `@handle`s.                                                 |
| `create_character` | Saves a private character from an image link, optionally with a voice clip.                 |
| `delete_character` | Deletes one of your characters.                                                             |
| `list_references`  | Lists your outfits, poses, locations, objects, and voice clips, all of them or one kind.    |
| `create_reference` | Saves a private reference from an image or audio link.                                      |
| `delete_reference` | Deletes one of your references.                                                             |
| `list_history`     | Lists your generations from the last 30 days, including the ones you made in Mage yourself. |
| `search_creations` | Searches the creations you saved, by what they show, by collection, or by date.             |

Mention a saved character or reference in a request with its handle, for example "Make a portrait of @ana wearing @red-coat", and your assistant passes it to the model.

## How generations work

1. Your assistant picks a model with `list_models` and reads its fields with `get_model`.
2. It checks the price with `estimate_cost`. A video input's price depends on its length, which Mage measures when the generation starts.
3. It starts the generation with `generate`, which charges your Gems. Each generation carries a key your assistant makes up, so a retry after a dropped connection returns the same generation instead of paying twice.
4. It waits with `get_request` until the result is ready and gives you the link.

Results stay available for 30 days: download what you want to keep, or save it in Mage. A result flagged by moderation as NSFW is marked as such. See [Requests](/api/requests) for the states a generation goes through and [Billing](/api/billing) for how Gems are charged.

## Images and files

Media inputs, such as a first frame or a reference image, are links: a public `https` URL or a data URL. Your assistant cannot read files you attach to the chat itself, so share a public link to the image instead, or use a creation already on Mage.

## Manage connected apps

Every app you connected is listed in [API → API Keys](https://www.mage.space/api?tab=keys) under **Connected apps**, with when you connected it and when it was last used. Select **Disconnect** to stop an app at once; it can no longer use your account or spend your Gems until you connect it again. You can also reach the list from **Settings** → **Account** → **Manage Connected Apps**.

## Limits

* Up to 20 generations can run at once for your account, as with the [API](/api/limits).
* An app can make up to 120 tool calls a minute.
* `get_request` waits up to 2 minutes per call; your assistant calls it again for longer generations.

## Troubleshooting

* **"Couldn't reach the MCP server"**: check that the URL is exactly `https://mcp.mage.space/mcp`, then remove the connector and add it again.
* **The connection asks you to sign in again**: the connection lasts up to 180 days, after which the app asks you to approve it again. Disconnecting in Mage also ends it.
* **A generation failed with `insufficient_gems`**: add Gems in [API → Billing](https://www.mage.space/api?tab=billing) and try again.