Use Mage from Claude, Cursor, and ChatGPT

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.

Server URL

https://mcp.mage.space/mcp

The MCP server is in early access. If connecting fails, write to [email protected].

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
Cursor

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

In Claude, open Customize → Connectors, add a custom connector, and paste https://mcp.mage.space/mcp as its URL. 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.

Custom connectors need ChatGPT’s developer mode, available on paid plans in ChatGPT on the web.

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

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 to Cursor with one click, or add it to ~/.cursor/mcp.json 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 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

Your assistant picks a model with list_models and reads its fields with get_model.
It checks the price with estimate_cost. A video input’s price depends on its length, which Mage measures 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 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 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.
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 and try again.

Get started

Concepts

Endpoints

Models

Image models

Video models

Audio models

Use Mage from Claude, Cursor, and ChatGPT

Connect your assistant

What your assistant can do

How generations work

Images and files

Manage connected apps

Limits

Troubleshooting

​Connect your assistant

​What your assistant can do

​How generations work

​Images and files

​Manage connected apps

​Limits

​Troubleshooting

Connect your assistant

What your assistant can do

How generations work

Images and files

Manage connected apps

Limits

Troubleshooting