Connect with MCP

Aether runs a remote Model Context Protocol (MCP) server. AI assistants that support MCP, such as Claude, Claude Code, Cursor, Antigravity, Codex and ChatGPT, can use it to generate images, effects and sprites and to tune images with your Aether account.

Server URL

https://api.aetherforgeai.com/mcp

The server uses the Streamable HTTP transport.

Connect with your Aether account (recommended)

Add the server URL to your client. The first time the client connects, your browser opens the Aether connection page.

1. Log in to Aether if you are not logged in yet. You return to the connection page automatically.
2. Check the client name and the address you will be sent back to.
3. Select Connect.

The client then receives its own access token. Access tokens expire after one hour and the client renews them automatically.

Pick your client:

Claude Code

claude mcp add --transport http aether https://api.aetherforgeai.com/mcp

Then run /mcp in Claude Code and choose aether to start the login.

Claude

In Claude (web and desktop), open Settings → Connectors → Add custom connector, enter the server URL and select Add. Then select Connect to start the login. Claude cannot upload files from the chat, so pass the job_id of an earlier result to image inputs.

Cursor

Add the server to mcp.json (Settings → MCP). When the server shows Needs login, select it to start the login in your browser.

{
  "mcpServers": {
    "aether": {
      "url": "https://api.aetherforgeai.com/mcp"
    }
  }
}

Antigravity

Register the server with the Antigravity CLI and start a session. The login opens in your browser the first time the server is used. If the browser cannot return to the CLI, paste the final URL from the address bar when the CLI asks for it.

agy mcp add aether https://api.aetherforgeai.com/mcp
agy

Codex

Register the server and log in. The login opens in your browser.

codex mcp add aether --url https://api.aetherforgeai.com/mcp
codex mcp login aether

ChatGPT

In ChatGPT, open Settings → Connectors → Advanced → Developer mode and select Create. Enter a name and the server URL, choose OAuth for authentication, then select Create and Connect to start the login. ChatGPT cannot upload files from the chat, so pass the job_id of an earlier result to image inputs.

Connect with an API key

Clients that can send custom headers can use an API key instead of logging in. Claude and ChatGPT connectors only support account login.

Authorization: Bearer <api_key>

Claude Code

claude mcp add --transport http aether https://api.aetherforgeai.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor

Add a headers entry to the server in mcp.json.

{
  "mcpServers": {
    "aether": {
      "url": "https://api.aetherforgeai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Antigravity

agy mcp add --header "Authorization: Bearer YOUR_API_KEY" aether https://api.aetherforgeai.com/mcp

Codex

Codex reads the key from an environment variable.

export AETHER_API_KEY=YOUR_API_KEY
codex mcp add aether --url https://api.aetherforgeai.com/mcp --bearer-token-env-var AETHER_API_KEY

Tools

Every tool uses the same options and credit costs as the matching page in the web app.

Tool	Web feature	Credit cost
create_image_upload	Upload an image for other tools	Free
get_job_status	Job status and result URLs	Free
get_credit	Credit balance	Free
list_my_ai_models	Models available for Aether generation	Free
list_my_results	History (tool, sprite, aether)	Free
generate_image	Generate image	1 (GPT Image 2), 2 (GPT Image 2.5 High, Nano Banana Pro), 3 (GPT Image 2.5 XHigh)
generate_effect_v1	Generate effects, V1 tab	5 (1K), 7 (2K), 10 (4K)
generate_effect_v2	Generate effects, V2 tab	3
upscale	Upscale	5 (1K), 7 (2K), 10 (4K)
inpaint_v1	Inpaint, V1 tab	5
inpaint_v2	Inpaint, V2 tab	3
remove_background	Remove BG	1
equip_variation	Equip variation	5
sprite_lite	Sprite Lite	5 to 13 by frame count
sprite_plus	Sprite Plus	9 (49 frames), 13 (81 frames)
sprite_zenith	Sprite Zenith	9 (36 frames), 25 (100 frames)
sprite_pulsar	Sprite Pulsar	3, or 4 for Sprite To Sprite
aether_generate	Aether	Free for included models, otherwise 2. list_my_ai_models shows credit_cost per model

Field names and allowed values are the same as the matching endpoint pages.

Results

Generation tools start an asynchronous job and return a job_id right away. Call get_job_status with that job_id to get the result. Set wait_seconds (up to 60) to wait for the job before the tool returns. When status is Succeed, image_urls holds the result image, and the GIF for sprites. See Asynchronous Job Lifecycle for the status values.

generate_image also creates a chat room on the web History page, listed under the API/MCP tab. The chat_room_id in the result identifies it, and you can keep generating in that room on the web.

Image inputs

Image fields take one of these:

• An upload_id from create_image_upload. Call the tool with the image's Content-Type, upload the file to the returned upload_url with an HTTP PUT within 5 minutes, then pass the upload_id.
• The job_id of one of your finished jobs, to reuse its result image. This lets you chain tools, for example upscale and then remove_background.

curl -X PUT -H "Content-Type: image/png" --data-binary @character.png "<upload_url>"

Send exactly the Content-Type returned by the tool. Images can be up to 20MB. Uploading needs a client that can run commands or send HTTP requests, such as Claude Code, Cursor, Antigravity or Codex. In chat apps that cannot upload files, reuse a finished job_id instead.

Errors

A failed tool call returns an error message instead of a result. When you do not have enough credits, the message links to the pricing page.