Skip to content
Immersive AI
Model Context Protocol

Use Immersive AI as tools in your agent.

One remote server for Claude, Claude Code, Codex, Gemini CLI, Cursor, Windsurf and any other MCP client. Sign in once with OAuth and the client discovers every image, video, audio, text and 3D tool.

Quick start API reference
Tools
42
Generation, jobs and discovery
Sign-in
OAuth
Or an API key as a Bearer token
Pay per call
x402
USDC on Base, no account
On this page

What MCP is

The Model Context Protocol is an open standard that lets AI assistants discover and call external tools. This server exposes the Immersive AI API as tools, so an assistant can generate images, video, audio, text and 3D assets for you and check on the jobs it started.

The tools take the same parameters as the REST API and are billed the same way, from the credits of the account you sign in with.

Quick start

Add a remote MCP server with this URL to your client, then sign in when it opens the authorization page.

https://dev.ai.immersive.inc/mcp

Your browser blocked the clipboard. Select the text and copy it by hand.

Setup guides

Pick your client.

Claude (claude.ai and Claude Desktop)

  1. Open Settings → Connectors.
  2. Choose Add custom connector.
  3. Paste the server URL: https://dev.ai.immersive.inc/mcp
  4. Claude opens the authorization page. Sign in and approve access.

Connectors added in Claude are available in Claude Desktop too. The claude_desktop_config.json file only starts local (stdio) servers, so add this remote server as a connector rather than in that file.

Claude Code

Add the server from your terminal:

claude mcp add --transport http immersive-ai https://dev.ai.immersive.inc/mcp --scope user

Your browser blocked the clipboard. Select the text and copy it by hand.

Then run /mcp in a Claude Code session and choose Authenticate to sign in.

Scopes: user makes the server available in all your projects, project shares it with your team through .mcp.json, and local (the default) keeps it to you in the current project.

Codex CLI

Add the server to ~/.codex/config.toml:

[mcp_servers.immersive-ai]
url = "https://dev.ai.immersive.inc/mcp"

Your browser blocked the clipboard. Select the text and copy it by hand.

To use an API key instead of OAuth, add bearer_token_env_var = "IMMERSIVE_API_KEY" to the same table and export the key in that variable. Check the connection with codex mcp list.

Gemini CLI

Add the server with one command:

gemini mcp add --transport http immersive-ai https://dev.ai.immersive.inc/mcp --scope user

Your browser blocked the clipboard. Select the text and copy it by hand.

Or add it to ~/.gemini/settings.json:

{
    "mcpServers": {
        "immersive-ai": {
            "httpUrl": "https://dev.ai.immersive.inc/mcp"
        }
    }
}

Your browser blocked the clipboard. Select the text and copy it by hand.

Restart the CLI and run /mcp to check the connection.

Cursor

  1. Open Settings → Tools & MCP.
  2. Choose New MCP server.
  3. Add the server below and save. A green dot shows that it connected.
{
    "mcpServers": {
        "immersive-ai": {
            "url": "https://dev.ai.immersive.inc/mcp"
        }
    }
}

Your browser blocked the clipboard. Select the text and copy it by hand.

Windsurf

Add the server to ~/.codeium/windsurf/mcp_config.json:

{
    "mcpServers": {
        "immersive-ai": {
            "serverUrl": "https://dev.ai.immersive.inc/mcp"
        }
    }
}

Your browser blocked the clipboard. Select the text and copy it by hand.

Open Cascade → Manage MCPs and choose Refresh.

Authentication

Every request to the server needs a Bearer token. There are two ways to get one.

OAuth (recommended)

Clients that support OAuth handle it for you. The first request returns 401 with a WWW-Authenticate header that points to the server's metadata, and the client then:

  1. reads /mcp/.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server,
  2. registers itself at /mcp/register (dynamic client registration),
  3. opens /mcp/authorize, where you sign in and approve access,
  4. exchanges the authorization code (with PKCE, S256) for a token at /mcp/token.

On the consent screen you choose who pays for the app's requests: your personal credits or a team you own or administer. You can also cap what the app may spend at 500, 1,000 or 5,000 credits, a custom amount, or leave it without a limit.

Each app gets one API key, named after the app with “(MCP)” at the end. When the app connects again, that key is replaced rather than a second one added.

API key

If your client can't run OAuth, create an API key after you create an account and send it as a header. Most clients accept a headers object next to the URL: 

{
    "mcpServers": {
        "immersive-ai": {
            "url": "https://dev.ai.immersive.inc/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
            }
        }
    }
}

Your browser blocked the clipboard. Select the text and copy it by hand.

Generation tools

These tools call the API and spend credits. Media jobs run asynchronously: call get_status with the returned id until the result is ready.

Image

  • image_generate Generate an image from a text prompt.
  • image_edit Edit an existing image using natural language instructions.
  • image_upscale Upscale a low-resolution image to higher resolution using AI super-resolution.
  • image_remove_background Remove the background from an image, outputting a transparent PNG.

Video

  • video_generate Generate a video from a text prompt or image.
  • video_effects Apply visual effects to an image, creating a short animated video.
  • gemini_omni_character_create Register a reusable Gemini Omni character (1 image + description) via KIe.
  • gemini_omni_voice_create Register a reusable Gemini Omni voice from one of 30 preset voice IDs + optional metadata.
  • gemini_omni_voice_presets List the 30 preset voice IDs available for gemini_omni_voice_create.

Audio

  • audio_tts Convert text to natural-sounding speech using OpenAI or ElevenLabs TTS.
  • audio_stt Transcribe audio using OpenAI Whisper or ElevenLabs Scribe v2.
  • audio_sts Speech-to-speech voice conversion using ElevenLabs.
  • audio_music Generate music from a text prompt.
  • audio_suno_extend Extend an existing Suno track by its audioId.
  • audio_suno_upload_extend Extend an externally-hosted audio file (≤8 min) with new Suno content.
  • audio_suno_upload_cover Re-imagine an externally-hosted audio file (≤8 min) in a new style.
  • audio_suno_add_instrumental Generate an instrumental backing for an uploaded audio file.
  • audio_suno_add_vocals Generate a vocal track over an uploaded instrumental.
  • audio_suno_separate_vocals Split a previously-generated Suno track into vocals + instrumental, or full stems.
  • audio_suno_wav Convert a previously-generated Suno track to WAV.
  • audio_suno_lyrics Generate 2–3 lyric variations from a short theme.
  • audio_suno_timestamped_lyrics Get word-level aligned lyrics + waveform for a generated Suno track.
  • audio_suno_boost_style Expand a concise style description into a richer one.
  • audio_suno_music_video Render an MP4 music video for a previously-generated Suno track.

Text

  • text_generate Generate text using AI (OpenAI, Anthropic, OpenRouter, Gemini).
  • text_chat Chat completion with message history.
  • text_translate Translate text to a target language using AI.
  • text_decide Ask typed questions about a piece of text or JSON and get calibrated answers instead of prose, via TypeSafe's Jev decision model on OpenRouter.

3D

  • threed_generate Generate a 3D asset from a text prompt or image.

Jobs and account

  • get_status Poll the status of an async generation job.
  • get_credits Check your current credit balance.

Discovery tools

These help an agent explore the API and don't spend credits.

  • get_api_info Base URL, authentication and the API categories.
  • authenticate How to get an API key.
  • get_endpoints Every endpoint, optionally filtered by category.
  • get_endpoint_implementation_guide A full implementation guide for one endpoint.
  • generate_working_curl A working cURL command built from real examples.
  • generate_multi_language_examples The same request in Python, JavaScript, cURL, PHP, Go and Java.
  • get_pricing_analysis The cost breakdown of an endpoint.
  • find_similar_endpoints Related endpoints.
  • check_agent_status Connection and credit check.
  • get_x402_payment_info Wallet, network, USDC contract and credits per USDC.
  • get_x402_endpoint_cost The USDC amount for one endpoint and its parameters.

Resources

Machine-readable documents an agent can read without calling a tool.

  • openapi://ai-api Full OpenAPI specification (YAML)
  • openapi://ai-api/index Endpoint index (JSON)
  • openapi://ai-api/tags Available tags
  • openapi://ai-api/tag/{slug} OpenAPI slice for one tag
  • postman://ai-api Postman collection
  • database://ai-api/endpoints Endpoints with pricing and examples
  • x402://ai-api/payment-info x402 payment requirements

x402 payments

Agents without an account can pay per request in USDC on Base. Two tools support it: get_x402_payment_info returns the wallet, network and rate, and get_x402_endpoint_cost returns the exact amount for a request. The x402 guide walks through the payment flow.

Troubleshooting

“Authentication required” when connecting

That 401 is how the server starts OAuth. If your client doesn't open the sign-in page, it may not support OAuth for remote servers; use an API key header instead.

The event stream disconnects

The server sends a keep-alive event every 2 seconds on GET /mcp. If the stream drops, check that no proxy between you and the server buffers server-sent events.

“Insufficient credits”

Call get_credits to see your balance, then buy credits in the console or pay per request with x402.

Protocol details

  • Transport: HTTP. JSON-RPC requests over POST /mcp, a server-sent event stream over GET /mcp.
  • Protocol version: the server answers with the version the client sends, 2025-06-18 when it sends none.
  • Authentication: OAuth authorization code with PKCE (S256), or an API key as a Bearer token.