MCP server.

With it connected, the agent can look up GPU types and live prices, provision instances, deploy application templates, start fine-tuning jobs, watch what is running, and terminate it when the work is done, without you leaving the editor and without pasting anything into a dashboard.

It is a local stdio server: your client spawns it as a subprocess and talks JSON-RPC to it over stdin/stdout. Nothing is hosted, nothing is proxied, and your API key never leaves your machine: the server calls https://api.gpu.ai/v1 directly, exactly as the CLI and the SDKs do.

§ 20.1Install¶

The server is published to npm as @gpuai/mcp and runs on Node 22 or newer:

npx -y @gpuai/mcp@latest

You do not normally run that by hand — your MCP client runs it for you, using the configuration in the next section. There is nothing to install globally and no separate npm install step: npx fetches the package on first launch and caches it.

§ 20.2Client setup¶

The API key is passed only through the environment block of your client's MCP configuration. It is never a command-line flag: arguments show up in ps output and shell history, and a credential does not belong in either.

§20.2.1Claude Code¶

Create .mcp.json in your project root, or edit the existing one:

{
  "mcpServers": {
    "gpuai": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@gpuai/mcp@latest"],
      "env": {
        "GPUAI_API_KEY": "${GPUAI_API_KEY}"
      }
    }
  }
}

Claude Code expands ${GPUAI_API_KEY} from your shell environment when it spawns the server, so the key stays out of the file and out of version control. Export it once in your shell profile:

export GPUAI_API_KEY=gpuai_live_...

Claude Code can also write this entry for you with claude mcp add. Restart the session afterwards, then ask the agent to check gpu_auth_status: if the key is wired correctly it comes back with your spend envelope.

§20.2.2Claude Desktop¶

Claude Desktop launches servers with a minimal environment and does not expand shell variables or inherit your shell profile, so the value is written literally:

{
  "mcpServers": {
    "gpuai": {
      "command": "npx",
      "args": ["-y", "@gpuai/mcp@latest"],
      "env": {
        "GPUAI_API_KEY": "gpuai_live_..."
      }
    }
  }
}

The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Restart the app after editing it.

Any other MCP client works the same way: a command, its arguments, and an environment block carrying GPUAI_API_KEY. Cursor's mcp.json uses the same mcpServers shape as Claude Code.

§ 20.3Authentication¶

Mint a key in the dashboard. It is the same key the gpu CLI uses, so one export covers both tools.

The server fails fast, and offline. At startup it checks only that the key is present and that a base-URL override is a valid absolute http(s) URL. It makes no network call at boot, so a flaky connection can never look like a bad key, and a bad key surfaces as a clear “check GPUAI_API_KEY” message on the first tool call rather than as a mysterious startup failure.

The key is never echoed. It is not returned by any tool, not written into any error message, and not included in a confirmation prompt. Every error string the server produces passes through a redaction step first, so even an API response that echoed a credential back would be scrubbed before you saw it.

§20.3.1Use a dedicated key¶

Mint a separate API key for agent use rather than reusing the one in your CI or your laptop's shell profile. Two concrete benefits: independent revocability (if anything looks wrong you revoke that one key and the agent stops, while your pipeline and your own CLI keep working) and clean attribution, so “what did the agent spend” is answerable.

If the agent only needs to look things up, mint a read_only key. All 11 free tools work with one, and the four money tools structurally cannot be called with it. The API rejects the write before the request reaches provisioning.

There is also no “who am I” endpoint on the public API, and this server does not invent one. gpu_auth_status proves your key works and shows your spend envelope; it does not report an account identity.

§ 20.4Base URL¶

GPUAI_API_BASE overrides the API base URL for custom, self-hosted or staging endpoints. Leave it unset and every call goes to production:

"env": {
  "GPUAI_API_KEY": "${GPUAI_API_KEY}",
  "GPUAI_API_BASE": "https://api.internal.example.com/v1"
}

• Unset always means production. There is no hidden non-production default. A tool that silently pointed at the wrong environment would look like it was working while touching the wrong account and the wrong invoice.
• The guardrail does not relax on a non-production base URL. Quote, confirm, execute applies identically wherever you point it. There is no “it's only staging” path through the confirmation.

§ 20.5The spend guardrail¶

Four of the fifteen tools can create a charge or destroy something you are paying for. All four go through the same two-call handshake, and it is the server that enforces it, not the tool description, and not the agent's judgment. A client that ignored every hint the server publishes still could not reach a charge without a confirmation.

1. The agent calls the tool. Nothing is provisioned. The server resolves your request against live pricing (including the region, and including "auto" GPU selection, so what gets priced is a specific machine) and returns a price summary plus a single-use confirmation token. No write is made.
2. You see the price. 2x h100_sxm (on_demand) in us-west-2 at $4.98/hr, with the 24-hour estimate and a reminder that it keeps billing until terminated. If capacity is not currently available at that configuration, or the figure is derived rather than quoted, the summary says so instead of quietly implying a launch will succeed.
3. You say yes. The agent calls the tool again with the token and the same parameters. Only then does anything get created.

The token is single-use, short-lived, and bound to the parameters that were quoted. Confirming with anything changed (a different GPU count, a different tier, a different instance id) does not execute; it re-quotes at the new price and asks again. So an approval cannot be carried over onto a bigger machine than the one you priced.

• One confirmation covers one call. The next create asks again.
• A pre-authorization given before the price existed does not count. Telling the agent up front to skip the questions unlocks nothing: the token is minted by the quote, and there is no quote until the price has been looked up.
• Hardware is always explicit. GPU type, count (1–8) and tier are required fields with no defaults. An omission is a rejected call, not a silent decision. Auto-selection is available on template deploys, but only by passing the literal "auto" (a choice, not a forgotten field).
• A confirmed launch cannot cost more than the number you approved. When you set no price ceiling, the quoted price (an estimated one included) becomes the ceiling, so the API itself refuses to place above the number you approved. A request that cannot be priced at all is refused outright rather than quoted. The one exception is a custom disk_gb: extra disk folds into the hourly rate, so no automatic ceiling is applied there. Set max_price_per_hour yourself to bound those launches.
• A failed call is never silently retried. A create that errored may have partially provisioned; the agent is told to report it and re-confirm rather than risk double billing.
• Fine-tuning is capped, not quoted. A training job has no fixed price (it bills for as long as it runs), so gpu_fine_tuning_create requires max_budget_usd. That cap is the number that bounds the job. Passing 0 means no cap, and should only ever be a decision you made out loud.

Where a client supports MCP elicitation, the server asks you directly in that client's own UI. Support for this is uneven and many clients, including scripted and CLI-driven ones, do not advertise it, so the flow you will normally see is the two-call handshake with the agent relaying the quote. Both paths run through the same enforcement; elicitation is nicer UX on top of it, never a replacement for it.

§ 20.6Tool reference¶

§20.6.1Free and read-only (11)¶

None of these mutate anything, none cost money, and all of them work with a read_only key.

§20.6.2Money tools (4)¶

Each one quotes first and requires an explicit confirmation, as described above.

§ 20.7Provisioning is asynchronous¶

A confirmed create or deploy never blocks. It returns an operation id immediately, as the first line of the response, and the agent is instructed to report that id to you straight away. It is the only handle on a request that may already be spending money, and a call that dies mid-flight must not take the id with it.

1. Poll gpu_operations_get with that id, on a backoff: 2s after the first call, increasing by 1s each time to a maximum of 10s. Terminal states are succeeded, failed and cancelled; anything else means keep going. This is the same cadence the CLI uses.
2. On failed, check for leftovers. A failed provision can still leave a running, billing instance. The tool descriptions tell the agent to list instances and terminate anything billable left behind, but it is worth knowing that is the expected recovery, not an exception.
3. Nothing stops on its own. Billing starts when the instance runs and continues until gpu_instances_terminate succeeds. Terminate, then verify: list instances afterwards and confirm.

Provisioning capacity can take around fifteen minutes on slow-boot hardware. allocating means capacity is still being acquired, starting means the machine exists and is booting, and running means it is ready.

§ 20.8Related¶

• The gpu CLI: the same capabilities from a terminal.
• TypeScript SDK and Python SDK: the typed clients underneath.
• Endpoint reference: every /v1 endpoint the tools wrap.