GMI MCP Server - GMI Cloud Documentation

One HTTP endpoint that lets an AI assistant use your GMI Cloud account: browse the model catalog, quote a job before you pay for it, generate images and video, and read your balance.

The server lives at https://mcp.gmicloud.ai/mcp. You connect it once through a browser sign-in. After that, you describe what you want in plain language, and the assistant picks the tools. You write no integration code. This page covers Claude Code end-to-end and gives the one-line setup for Codex CLI, Cursor, and Claude on web and desktop.

Prerequisites

A GMI Cloud account at console.gmicloud.ai, in an organization with a balance
An MCP client installed and working: Claude Code, Codex CLI, Cursor, or Claude web/desktop
A browser on the same machine, for the one-time sign-in
About 5 minutes

You do not paste a token into a config file. The connection uses a browser sign-in, and your client stores the credential it produces.

Two GMI credentials, if you also run Claude Code on GMI models

They are different things and they fail differently. The error messages do not say which one broke.

Credential	What it does	Where it lives
Inference API key	Lets Claude Code use GMI models to think	`ANTHROPIC_AUTH_TOKEN`, see Claude Code
MCP authorization	Lets the assistant use the tools on this page	Browser sign-in, nothing to paste

This page sets up the second one only. If you have not pointed Claude Code at GMI as a model provider, you have just the MCP authorization and can skip this table.

Step 1. Connect your client

Every client points at the same URL:

https://mcp.gmicloud.ai/mcp

Find your client below. You only need the one section that matches it.

Claude Code

Claude Code is Anthropic’s terminal CLI. Connect it with one command:

claude mcp add --transport http gmi https://mcp.gmicloud.ai/mcp

gmi is the local name you see in listings. Rename it if you prefer. The server registers for the current project only. Add --scope userto get it in every project:

claude mcp add --transport http --scope user gmi https://mcp.gmicloud.ai/mcp

To commit the server alongside a project instead, put this in .mcp.json at the project root:

{
  "mcpServers": {
    "gmi": {
      "type": "http",
      "url": "https://mcp.gmicloud.ai/mcp"
    }
  }
}

Confirm it with claude mcp list, then continue to Step 2. Claude Code and Claude are different products and connect differently. Claude Code uses the claude mcp add command above. Claude on web and desktop uses the Connectors screen below. Doing one does not set up the other.

Claude (web and desktop)

Go to Settings → Connectors, or open claude.ai/customize/connectors.
Click Add custom connector.
Name it GMI Cloud and paste https://mcp.gmicloud.ai/mcp.
Click Connect and sign in with your GMI account.

Connectors attach to your Claude account, not to a machine, so adding one makes it appear in both the web app and the desktop app. There is nothing to edit in claude_desktop_config.json. On Team and Enterprise plans, only a workspace owner can add the organization’s connector. Everyone else then connects to it individually, so you may need to ask.

Codex CLI

Codex CLI is OpenAI’s terminal CLI. It takes two commands, one to add the server and one to sign in:

codex mcp add gmi --url https://mcp.gmicloud.ai/mcp
codex mcp login gmi

Codex requests every scope the server offers, including the one needed to submit a generation, so generation works right after codex mcp login. You can also name the scopes yourself:

codex mcp login gmi --scopes models:read,generation:read,generation:write,billing:read

Codex CLI and ChatGPT are different products and connect differently. Codex CLI uses the codex mcp commands above. ChatGPT uses its connector settings below.

ChatGPT

Add https://mcp.gmicloud.ai/mcp as a connector in ChatGPT’s settings, then sign in with your GMI account when prompted. ChatGPT is the one client where you can attach a local file directly in the chat. The server reads that attachment and uploads it for you, so you skip the manual upload described in Step 6. Every other client needs the three-step upload.

Cursor

Add the server to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gmicloud": {
      "url": "https://mcp.gmicloud.ai/mcp"
    }
  }
}

Then open Cursor’s MCP settings and connect it.

Any other MCP client

The server is a standard remote MCP server over HTTP with OAuth. Point your client at https://mcp.gmicloud.ai/mcp and complete the browser sign-in. Nothing on this page is client-specific after that. Some clients request read-only access on a first connection, which lets you browse and price but not generate. If a generation comes back refused, see insufficient scope. The first time your assistant reaches for a GMI tool, a browser tab opens. You sign in to GMI Cloud, then an approval screen names the organization being connected and the access being asked for. You register no application by hand. Your client identifies itself to the server as part of the flow. A standard connection asks for four read-only items:

Scope	What it grants
`models:read`	See which models are available, and their details
`generation:read`	See your recent generation requests
`billing:read`	See your balance and usage
`profile:read`	See your name and email

Choose Cancel and nothing is granted. Approve, and the tab hands control back to your terminal. billing:read exposes your organization’s balance in dollars, not just its usage. That is what makes spend checks work. If your organization would rather not expose that figure, do not approve the connection. Submitting a generation or uploading media needs write access, which is deliberately not part of a read-only connection. Connecting can never spend your balance by accident. The approval screen shows only what your client asked for, and you cannot add access there.

Step 3. Confirm it worked

claude mcp list

Look for a line reporting gmi connected over http. Inside a running Claude Code session, type /mcp and pick the server to see its connection state and the tools it offers. Then ask something that touches nothing and costs nothing:

What video models does GMI have?

If a list of models comes back, everything above worked.

Step 4. Your first generation

You do not call tools yourself. You describe what you want. A good run has four beats: find a model, read its parameters, price the job, then submit it.

Find me a GMI model that turns a photo into a short video. Check what parameters it takes, tell me what five seconds at 720P would cost, and wait for me before submitting anything.

Behind that, the assistant browses the catalog, inspects the model you settle on, and gets a real quote from GMI instead of guessing. Telling it to stop before submitting is the habit that keeps surprises out of your bill. Parameters differ per model, not per media type. Two video models will disagree about what the first-frame field is called and what resolution values they accept. The assistant has a tool that reads a model’s real parameter list. Let it, and the request comes out shaped correctly the first time.

Audio works the same way

The server generates audio as well as images and video. Text-to-speech, voice cloning and music models are all in the catalog, priced per character or per request rather than per second:

What text-to-speech models does GMI have, and what would 500 characters cost?

The four-beat pattern above does not change. Only the parameters and the pricing unit do, which is why get_model comes before every submission.

Step 5. Video takes minutes, not seconds

An image usually comes back while you wait. Video does not. A video request hands you a tracking id right away instead of holding the session open:

Still running. This generation was accepted and is being charged; it did not fail.
Call get_generation with request_id "req_..." to get the result.

Read that carefully: accepted and being charged. It is not an error and not a timeout. The job runs on GMI’s side. Come back to it whenever:

Is that video done yet?

To wait in place for a short job instead, say so. The assistant can hold for up to 90 seconds before handing back an id. That is rarely long enough for video: a 5 second 720P clip took about six minutes end to end in testing, so expect to poll rather than wait. An image is the opposite. A text-to-image request usually returns the finished media in the same call, with no id to poll.

A worked example: wan3.0-video

Everything in this table comes from the model’s own declaration, which is why asking the assistant to read it beats guessing.

Parameter	Accepts	Default	Notes
`prompt`	text, up to 5000 characters	none	Required. Chinese and English both count one character per character. Longer text is truncated.
`first_frame`	a publicly reachable image URL	none	The still your video starts from. Pair it with `ratio: adaptive`to keep the photo’s own framing.
`resolution`	`480P`, `720P`, `1080P`	`1080P`	Case-sensitive, and it sets the per-second price. See the price table below.
`ratio`	`adaptive`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`	`adaptive`	`adaptive` follows the input media, and behaves like `16:9`when there is none.
`duration`	2 to 30 seconds	`5`	Price scales linearly with this.
`last_frame`	a publicly reachable image URL	none	Combine with `first_frame` to interpolate between two stills.
`reference_image`	one URL, or up to 10	none	Keeps a subject, character or style consistent across the video.
`reference_video`	one URL, or up to 5	none	Guides motion or style.
`audio_url`	a wav or mp3 URL	none	Drives the generated video. Audio longer than the video is cut to length.
`prompt_extend`	`true` / `false`	`true`	Rewrites short prompts for better results, at the cost of some generation time.
`watermark`	`true` / `false`	`false`	Adds the fixed text `AI Generated` to the lower-right corner.
`seed`	0 to 2147483647	random	Reusing a seed does not guarantee an identical result. Generation is probabilistic.
`negative_prompt`	text, up to 500 characters	none	What you do not want to appear.

What it costs

Price scales with both duration and resolution, so resolution is a pricing decision, not just a quality one:

Resolution	Per second	5 seconds	30 seconds
`480P`	$0.05	$0.25	$1.50
`720P`	$0.10	$0.50	$3.00
`1080P`(default)	$0.20	$1.00	$6.00

Omitting resolution gives you 1080P, the most expensive tier. Ask for a quote before you submit and you never learn this from an invoice.

The value that will bite you

resolution is case-sensitive, and a lowercase value is caught late. Sending 720p instead of 720P does not fall back to a default and does not stop at submission. estimate_generationprices it as if it were valid, submit_generation accepts it and returns a request id, and the job then ends as failed:

Input should be 1080P, 720P or 480P: parameters.resolution (code: InvalidParameter)

So estimate_generation prices a request, it does not validate one. The only guard against this is having the assistant read the real enum with get_model instead of filling the value in from memory.

Submitting the same request twice

Identical requests deduplicate. If your assistant submits the same model, prompt and parameters again inside the dedupe window, you get the original job back rather than a second charge. The window is longer for video than for image. That protects you from an accidental double-submit. It also means a deliberate second take of an identical request needs idempotency_nonce set to a new value. Changing anything in the prompt or parameters, including the seed, is enough on its own.

Step 6. Using your own image or video

Models take input media as a URL, not as bytes. In most clients you cannot paste a file into a tool call. ChatGPT is the exception: attach the file in the chat and the server handles the upload for you. Bringing your own photo is a three-move sequence, and the assistant can drive all of it:

Ask for an upload slot for your file type. You get back a one-time upload address and the public URL the file will live at.
Send the bytes to that address.
Pass the public URL as the model’s input parameter. For wan3.0-video that is first_frame.

I have a PNG at ./cat.png. Upload it and animate it into a five second 720P video with a slow camera push in.

Accepted file types are jpeg, jpg, png, mp4, mp3 and wav. The upload address is valid for 15 minutes. If you get a slot and then wander off, ask for a fresh one rather than retrying the old address.

Step 7. Keeping an eye on spend

What’s our balance, and what have we spent on tokens in the last week?

You get the organization’s balance in dollars, plus token usage and cost over the window you asked for, broken down by the models that used the most. The window is one day unless you name a longer one, and it can reach back 90 days. Ask for more than that and the request is refused outright rather than quietly trimmed to the maximum. If the answer looks too short, check what window you actually asked for. These usage figures cover text-model tokens. Spend on image and video generation is not part of that number. For those, use list_generations or the console. The balance figure does not move the moment a generation completes either. In testing, $0.53 of image and video generation left the reported balance unchanged, so generation billing settles on its own schedule. Treat the balance as a funding check, not as a live meter for a job you just ran. A negative balance does not block generation. Submissions still succeed while the balance is below zero, so the balance is not a spend guard. If you need one, quote every job with estimate_generation and approve it before submitting.

Tool reference

Ten tools. You will rarely name them, because the assistant chooses them. They are listed so you can tell what it is doing, and so you know what it cannot do.

Tool	What it does	Access needed
`search_models`	Find models by task, modality or provider	`models:read`
`get_model`	Read one model’s real parameters, availability and pricing	`models:read`
`estimate_generation`	Price a job before submitting it	`generation:read`
`list_generations`	Your recent generation requests and their status	`generation:read`
`get_generation`	Check one request and collect its media once ready	`generation:read`
`submit_generation`	Create a generation. Spends the balance.	`generation:writegeneration:read`
`upload_media`	Get an upload slot for your own input media	`generation:write`
`get_account_summary`	Balance, plus token usage and cost	`billing:read`
`search_docs`	Search GMI’s own documentation and return sections with links	none
`create_support_request`	File a support ticket against your organization	none

The last two are not about generation. search_docs answers how-to questions out of docs.gmicloud.ai instead of from the model’s memory, so ask your assistant a GMI question directly rather than guessing. create_support_request files a ticket, and every call files a new one, so do not repeat it after you get a submission id. No tool deletes anything, changes a setting, or moves money. The most consequential thing this server can do is spend your balance on a generation you asked for.

Working rules for the assistant

Paste this into your CLAUDE.md, AGENTS.md or project rules so an agent uses the server well without being told each time.

When using the GMI MCP server:

1. Call `get_model` before building any generation request. Never fill in
   parameters from memory. They differ per model, not per media type.
2. Enum values are case-sensitive and are validated late. `720p` is priced by
   `estimate_generation` and accepted by `submit_generation`, then the job
   fails. Copy enum values exactly as `get_model` spells them.
3. Call `estimate_generation` and report the price before calling
   `submit_generation`. Wait for the user to approve the spend. Treat the
   estimate as a price, not as validation; it does not check your parameters.
4. Price depends on resolution as well as duration, and omitting `resolution`
   selects the most expensive tier. State the resolution you priced.
5. `submit_generation` spends real money. Treat one call as one charge, and
   never retry it on your own initiative.
6. A video request returns a `request_id` instead of media. That is success,
   not a timeout. The job is accepted and being charged. Poll it with
   `get_generation` rather than resubmitting.
7. Input media must be a public URL. To use a local file, call `upload_media`
   for a slot, PUT the bytes, then pass the returned public URL. The slot
   expires in 15 minutes.
8. When a generation returns a failure reason, read it and fix the cause.
   An identical resubmission fails identically and is a separate job.
9. `get_account_summary` covers text-model tokens only. It does not include
   image or video generation spend.

Troubleshooting

Invalid API key, and the turn ends instantly

This is not an MCP problem, even when /mcp has just reported a successful connection. It means Claude Code could not reach a model, so it is your inference API key, not your MCP authorization. The one-second test: ask the assistant something that needs no tools at all, like what is 2 + 2. If that fails the same way, the problem is the inference key. If only tool-using requests fail, the problem is MCP. To confirm, check the key directly:

curl -s -o /dev/null -w '%{http_code}\n' \
  https://api.gmi-serving.com/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

401 means the key is the problem. Create a new one in the console and update it where you set it. An empty result from echo $ANTHROPIC_AUTH_TOKEN means the variable never loaded in this shell, which looks identical from the outside. See Claude Code for where to set it.

insufficient scope

The full message reads insufficient scope: [generation:write generation:read] required. Your connection was granted read access only, so it can browse and price but not submit. The approval screen reflects what your client requested, and you cannot add access to an existing grant from that screen. Disconnect and connect again so the authorization runs fresh, and read the approval screen before approving. Write access should be listed. If it is not offered at all, your client is not requesting it. Send that exact message to support@gmicloud.ai rather than retrying.

The browser tab never opened, or you closed it

Ask the assistant for anything that needs GMI again and the flow restarts. If nothing happens, check that claude mcp list shows the server at all. If it does not, the command in Step 1 did not take effect in the project you are in.

The service is currently unavailable

A message like The generation service is currently unavailable or The account summary is currently unavailable, with a upstream_unavailable code and a reference id, means the server reached GMI and GMI did not answer. It is not your connection, your scopes or your parameters. A submission that fails this way still appears in list_generations with status failed, so do not read that record as a job you need to chase. Retry once. These clear on their own. If one specific model keeps returning it while another model works, that model is down rather than the service, so pick another model or report the reference id to support@gmicloud.ai.

A generation came back with a failure reason

That text comes from the generation service, so it names the real cause: a rejected prompt, a bad parameter value, an unreachable input URL. Read it before retrying. An identical resubmission usually fails identically, and each attempt is a separate job.

A video request has been running a long time

Minutes are normal. Ask the assistant to check the request id. An accepted request is being charged whether or not you are watching, so cancelling and resubmitting is the expensive way to wait.

Everything is refused, and you have not signed in for a while

If a message says the token is no longer valid for its organization, your access needs authorizing again, most often because your organization membership changed. Reconnect.

Removing the server

claude mcp remove gmi

If you registered the server in more than one scope, name the one you mean with --scope local or --scope user. Removing the server stops your assistant from reaching GMI. It does not cancel generations already running, and it does not touch anything in your GMI account.

Next steps

Point your CLI at GMI models too: Claude Code, Codex, Cursor.
Browse what you can generate: Image, Video.
Stuck? Discord

​Prerequisites

​Two GMI credentials, if you also run Claude Code on GMI models

​Step 1. Connect your client

​Claude Code

​Claude (web and desktop)

​Codex CLI

​ChatGPT

​Cursor

​Any other MCP client

​Step 2. Sign in and approve access

​Step 3. Confirm it worked

​Step 4. Your first generation

​Audio works the same way

​Step 5. Video takes minutes, not seconds

​A worked example: wan3.0-video

​What it costs

​The value that will bite you

​Submitting the same request twice

​Step 6. Using your own image or video

​Step 7. Keeping an eye on spend

​Tool reference

​Working rules for the assistant

​Troubleshooting

​Invalid API key, and the turn ends instantly

​insufficient scope

​The browser tab never opened, or you closed it

​The service is currently unavailable

​A generation came back with a failure reason

​A video request has been running a long time

​Everything is refused, and you have not signed in for a while

​Removing the server

​Next steps