Use Mage from Claude, ChatGPT, Grok, and Cursor

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.

Server URL

https://mcp.mage.space/mcp

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
ChatGPT
Claude Code
Grok
Cursor

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

Open Connect Mage to Claude. The connector name and URL are filled in for you. Select Add.
Select Connect. A Mage page opens and asks you to sign in if you are not already.
Check that the page names the app you are connecting, then select Connect. You return to Claude.
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.

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

Open ChatGPT Plugins.
Click Add, then choose Create MCP App.
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.
Review the notice, check I understand and want to continue, then click Create.
Sign in to Mage on the page that opens, check the app’s name, and select Connect.
Install Mage from your Personal plugins, start a Work chat, and mention @Mage.

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.

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"

Add Mage as a custom MCP connector.

Open Grok connectors, select New Connector, then choose Custom.
Enter https://mcp.mage.space/mcp and complete the authentication prompts to connect your Mage account.
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.

Add Mage to Cursor to install Mage with its public OAuth client ID, then sign in to Mage when prompted. If Mage is already installed, replace its existing configuration with the one from this link.For manual setup, add this entry to ~/.cursor/mcp.json:

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:

mcp.json

{
  "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 `@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.

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

Your assistant picks a model with list_models, as above, and reads its fields with get_model.
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.
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.
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.

Get started

SDKs and integrations

Concepts

Endpoints

Models

Image models

Video models

Audio models

Use Mage from Claude, ChatGPT, Grok, and Cursor

Connect your assistant

What your assistant can do

Skills

Which model your assistant uses

How generations work

Images and files

Manage connected apps

Limits

Troubleshooting

​Connect your assistant

​What your assistant can do

​Skills

​Which model your assistant uses

​How generations work

​Images and files

​Manage connected apps

​Limits

​Troubleshooting

Connect your assistant

What your assistant can do

Skills

Which model your assistant uses

How generations work

Images and files

Manage connected apps

Limits

Troubleshooting