Mage

npx add-mcp 'https://mcp.mage.space/mcp'

Use Mage from Claude, ChatGPT, Grok, and Cursor

Connect Claude, ChatGPT, Claude Code, Grok, 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, Grok, 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.

https://mcp.mage.space/mcp

[!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.

Connect your assistant

Claude

Works in Claude on the web, the desktop app, the mobile apps, and Cowork.

1. Open Connect Mage to Claude. The connector name and URL are filled in for you. 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.

ChatGPT

Add Mage as a personal plugin from ChatGPT’s Plugins page.

1. Open ChatGPT Plugins.
2. Click Add, then choose Create MCP App.
3. Enter Mage for Name, https://mcp.mage.space/mcp for Server URL, and select OAuth for Authentication. Leave Advanced OAuth settings blank; no client ID or client secret is needed. The icon and description are optional.
4. Review the notice, check I understand and want to continue, then click Create.
5. Sign in to Mage on the page that opens, check the app's name, and select Connect.
6. Install Mage from your Personal plugins, start a Work chat, and mention @Mage.

[!NOTE]

If Create MCP App is missing, turn on Developer mode in ChatGPT’s Settings → Security and login, then return to Plugins. See ChatGPT’s setup guide for more details.

Claude Code

Add the server, then sign in from Claude Code:

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 instead of signing in:

claude mcp add --transport http mage https://mcp.mage.space/mcp \
  --header "Authorization: Bearer $MAGE_API_KEY"

Grok

Add Mage as a custom MCP connector.

1. Open Grok connectors, select New Connector, then choose Custom.
2. Enter https://mcp.mage.space/mcp and complete the authentication prompts to connect your Mage account.
3. Start a conversation and ask Grok to use Mage to create an image, video, or audio.

On Grok Business or Enterprise, a team admin must first provision the connector in the cloud console.

Cursor

The button installs Mage with its public OAuth client ID; sign in to Mage when prompted. If Mage is already installed, replace its existing configuration with the one from this link. If the button does nothing, open the web install link instead: it opens Cursor from the browser and shows the same configuration to add by hand.

For manual setup, add this entry to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mage": {
      "url": "https://mcp.mage.space/mcp",
      "auth": {
        "CLIENT_ID": "https://cursor.com/mcp",
        "scopes": [
          "mage",
          "offline_access"
        ]
      }
    }
  }
}

The client ID is public and needs no client secret. Cursor uses static OAuth configuration to open Mage’s consent page.

You can also connect with an API key:

{
  "mcpServers": {
    "mage": {
      "url": "https://mcp.mage.space/mcp",
      "headers": { "Authorization": "Bearer ${env:MAGE_API_KEY}" }
    }
  }
}

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 recommended models with their prices, what each is best for, and its trade-offs; the rest on request.
get_model	Describes one model: its fields, allowed values, defaults, rules, and price.
estimate_cost	Prices a generation before it starts. Nothing is charged.
create_upload	Gets a signed link to upload a file from your computer, for assistants that can run commands.
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 @handles.
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.

Skills

Mage skills teach your assistant complete jobs on top of these tools: product photoshoots, marketplace listings, ad variations, UGC and faceless videos, YouTube thumbnails, and the Mage apps, from face swaps and relighting to video edits and lip sync. Add them with npx skills add mage-space/skills, or browse them with examples at mage.space/skills.

Which model your assistant uses

Unless you name a model, your assistant makes images with Mango 3, video with Cherry 2 Pro, and audio with Seed Audio. It tells you the model and the price before it starts, and after a result it may suggest one alternative when its trade-off fits what you are doing.

	Images	Video
Default	Mango 3	Cherry 2 Pro
Same family	Mango 3S (cheaper, up to 3K), Mango 2 (up to 4K), Mango	Cherry Pro (4K), Cherry, Cherry Mini (the cheapest Cherry)
Also recommended	Guava 2 Pro and Guava 2 (photoreal), GPT Image 2.5 Flare (text and precise edits)	Lemon (first and last frames, clips up to 30 seconds)

Every other model runs only when you ask for it by name, for example "make it with Melon" or "use Nano Banana 2". Your assistant may suggest one when it suits a request better, such as an anime model for an anime clip, and waits for your answer. Which model should I use? compares them all.

Cherry 2 Pro is Mage's most capable and most expensive video model, and its price climbs steeply with resolution and length. Ask for Cherry Mini or Lemon while you are drafting.

How generations work

1. Your assistant picks a model with list_models, as above, and reads its fields with get_model.
2. It checks the price with estimate_cost, which also catches a request the model would refuse. A video's price depends on its length: Mage measures a video already on Mage, such as an uploaded file or an earlier result, when it quotes the price, and a video linked from another site only 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 for the states a generation goes through and Billing for how Gems are charged.

Images and files

Media inputs, such as a first frame, a reference image, or a video to edit, are links: a public https link to the file itself, or a data URL of up to about 3 MB.

• Claude Code, Cursor, and other assistants that run commands can upload a file from your computer: they get a signed upload link with create_upload, send the file to it, and use the file's new link like any other. A file can be up to 100 MB and is deleted after 30 days. Each upload holds one file: a corrected file goes up as a new upload, since the old link can keep showing the first file for up to 4 hours.
• Claude, ChatGPT, and Grok chats cannot pass a file you attach to the chat on to Mage. Share a direct link to the file instead, or use a creation already on Mage.
• A link to a web page, such as a YouTube or TikTok video, is not a file and is refused.

Manage connected apps

Every app you connected is listed in MCP → 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. Open MCP in the floating navigation, then select Connected apps.

Limits

• Up to 20 generations can run at once for your account, as with the API.
• 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

• Cursor says "Incompatible auth server: does not support dynamic client registration": update the existing Mage entry in ~/.cursor/mcp.json to include the auth block from the Cursor setup above, then reconnect. A server URL alone does not include Mage’s pre-registered Cursor client ID.

• "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 and try again.

This documentation is built and hosted on Mintlify, a developer documentation platform.