@gpuai/mcp
v0.6.0
Published
MCP server for the GPU.ai Public Developer API
Readme
GPU.ai MCP server
Connect Claude Code, Claude Desktop, Cursor, or any other MCP client straight to your GPU.ai account. The agent can look up GPU types and live prices, provision instances, deploy application templates, start fine-tuning jobs, run chat completions, manage SSH keys, webhook endpoints and GPU price/stock alerts, watch what is running, and terminate it when the work is done — without leaving the editor.
58 tools in three tiers: reads are free, writes confirm once, money tools quote a price and require explicit confirmation. The server enforces that, not the agent's good manners.
This is a local stdio server: your client spawns it as a subprocess and
talks JSON-RPC over stdin/stdout. Nothing is hosted and nothing is proxied —
your API key stays on your machine and the server calls
https://api.gpu.ai/v1 directly.
Full documentation: https://gpu.ai/docs/mcp
Requirements
- Node 22 or newer
- A GPU.ai API key — mint one in the dashboard
Setup
The key is passed only through your client's environment block. Never as a
command-line flag: arguments land in ps output and shell history.
Claude Code — .mcp.json
{
"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 when it spawns the
server, so the key stays out of the file and out of version control.
Claude Desktop — claude_desktop_config.json
Claude Desktop launches servers with a minimal environment and does not expand shell variables, so the value is written literally:
{
"mcpServers": {
"gpuai": {
"command": "npx",
"args": ["-y", "@gpuai/mcp@latest"],
"env": {
"GPUAI_API_KEY": "gpuai_live_..."
}
}
}
}macOS: ~/Library/Application Support/Claude/claude_desktop_config.json.
Windows: %APPDATA%\Claude\claude_desktop_config.json. Restart the app after
editing.
Restart your client, then ask the agent to check gpu_auth_status — if the key
is wired correctly it comes back with your spend envelope.
Configuration
| Variable | Required | Meaning |
| --- | --- | --- |
| GPUAI_API_KEY | yes | The API key the server authenticates with. The server refuses to start without it. |
| GPUAI_API_BASE | no | Base URL override for a custom, self-hosted, or staging endpoint. Unset means production (https://api.gpu.ai/v1). |
Startup is offline: the server presence-checks the key and validates the
base URL, and makes no network call at boot. A bad key surfaces as a clear
"check GPUAI_API_KEY" message on the first tool call, never as a mysterious
startup failure.
The key is never echoed — not in a tool result, not in an error message, not in a confirmation prompt. Every error string is passed through a redaction step first.
Use a dedicated key for agent work: it can be revoked on its own, and usage
attributes cleanly. If the agent only needs to look things up, a read_only
key covers all 28 free tools and structurally cannot provision or write. Note
that no key scope limits how much a key can spend — what bounds spend is
your organization's spending limit and the confirmation guardrail below.
The three tiers
| Tier | Tools | What happens before it runs |
| --- | --- | --- |
| Free, read-only | 38 | Nothing. No confirmation, no charge, no mutation. Works with a read_only key; never counts against the inference budget. |
| Writes — single confirmation | 11 | One confirmation. The server describes exactly what will change and returns a single-use token. No price line, because nothing is billed. |
| Money tools | 7 | A price. Six quote and confirm every call; chat completions confirm a session budget once and run inside it. |
The spend guardrail
Seven of the fifty-five tools can create a charge or destroy something you are paying for. Six of them (create, deploy, fine-tune, terminate, the deferred-spend auto-launch create, and job submit) go through the same two-call handshake:
- The agent calls the tool. Nothing is provisioned. The server resolves the
request against live pricing — including the region, and including
"auto"GPU selection — and returns a price summary plus a single-use confirmation token. No write is made. - You see the price.
2x h100_sxm (on_demand) in us-west-2 at $4.98/hr (~$119.52 est for 24h, and it keeps billing until terminated). - You say yes. The agent calls 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 a different GPU count, tier or 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.
It follows that: one confirmation covers one call; a pre-authorization given
before the price existed cannot unlock anything, because the token is minted by
the quote; GPU type, count and tier are required with no defaults, so an
omission is a rejected call rather than a silent decision; and when you set no
price ceiling the quoted price — an estimated one included — becomes the
ceiling, so a confirmed launch cannot cost more than 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.
gpu_instances_create also takes an optional dedicated_ip ({} for ports 80
and 443, or {"ports": [443, 8000]}), the dedicated public IP add-on. It is
billed on top of the instance, so the quote states its hourly fee, transfer
price, and transfer cap before anything is approved. The quote refuses it on a
deployment that does not offer the add-on, when your organization is at its
limit, when no address is free, and on the spot tier. Instance reads return it as
dedicatedIp.
Known-impossible launches are also refused at quote time: an instance launch
(create or template deploy) from an account with no SSH keys, an ssh_key_ids
entry that does not exist, a fine-tuning training_file that does not exist on
your account, or a fine-tuning base model the platform cannot tune
(gpu_models_list shows fineTunable and the exact fineTuneBaseModel id to
pass). Fine-tuning runs no SSH pre-flight — its key attachment is org-scoped
and checked at execution, as are per-key attach settings on a launch; those
still fail after confirmation, without billing. A pre-flight read that itself
fails never refuses the quote: "could not check" is not "checked and bad" — the
quote says which checks ran and which it could not verify, and the platform
still enforces the rule at execution.
Fine-tuning has no fixed price — it bills for as long as it runs — so
gpu_fine_tuning_create requires max_budget_usd, and that cap is what bounds
the job.
Every money quote — a provisioning price and a chat session budget alike — ends with one line covering inference spend this session, provisioning committed this session, and your organization's month-to-date total from the ledger, so a price is never approved in isolation from what has already been committed.
Each figure says what kind of number it is. Inference is billed — reconciled after every call against what the platform charges, which is whole cents rounded up per call, so the session budget stops you at the amount you approved rather than at a fractional-cent estimate of it. In-flight calls are estimated. Provisioning is quoted, not yet billed: one hour of the rate you approved, recorded as a floor, since an instance bills until it is terminated. The org ledger line is the authoritative total.
Where a client supports MCP elicitation the server asks you directly in that client's UI. Support is uneven, so the flow you will normally see is the handshake with the agent relaying the quote. Both run through the same enforcement.
Do not run a spend-capable agent in a blanket "auto-approve" mode. The server always asks for confirmation, but the client decides how that question is answered. With the client's own permission prompts disabled — for example Claude Code's
--dangerously-skip-permissionsor its "bypass permissions" mode — the client can auto-accept the confirmation on your behalf, and the price-then-confirm step stops being a human checkpoint. The server-side guardrail still holds (a token is minted only after a quote, single-use, parameter-bound), but an auto-answering client turns it into a formality. For any session that can spend money, leave approval prompts on, and set an organization spending limit in the dashboard so there is a ceiling no client mode can talk past.
Writes: one confirmation, no price
Seven tools change account state without billing anything — SSH keys, webhook endpoints, cancelling a fine-tuning job, renaming an instance, lowering the spending limit. No charge is not no consequence, so they get the same single-use, parameter-bound token machinery with the price line replaced by a consequence sentence:
gpu_ssh_keys_createstates that an SSH key grants persistent access to provisioned instances.gpu_ssh_keys_deletedoes not revoke access on instances already provisioned with the key.gpu_webhooks_createstates that GPU.ai sends event data to this URL. Its signing secret is returned exactly once, at creation, and is never readable again — store it when it appears, or delete and recreate the endpoint.gpu_instances_updateis rename-only; any other field is a parse error.gpu_fine_tuning_cancelroutes through the same balance preflight as starting a job, so at a zero or negative balance it returns 402 and the job keeps running and keeps billing. Add credit and call again.
Chat completions: a session budget
gpu_chat_completion is metered per token, and a typical call costs a fraction
of a cent — confirming each one would put a prompt in front of every message. So
it is approve once, run many, ask again at the wall:
- The first call in a session returns a $1.00 session budget quote and a
token. Propose a different figure with
session_budget_usd($0.01–$100). - Confirming approves the budget and runs that call. Calls inside the budget then run with no further confirmation.
- Any single call estimated above the $0.10 per-call ceiling is confirmed on its own even with budget headroom — the ceiling is checked before the budget gate, so an oversized call always surfaces as oversized.
- A spent budget sends the next call back to a fresh budget quote.
Costs are estimated from the model's published per-token rates against the
max_tokens bound, reserved before the call, and reconciled against the actual
usage afterwards; a failed call releases its estimate. The budget covers
inference only — provisioning and fine-tuning keep their own per-action
confirmation, and read-only tools never count. "Session" means one server
process: the budget does not survive a restart, because your approval did not.
Streaming is not available.
Spending limits are lower-only
gpu_spending_limit_get is a free read. gpu_spending_limit_update accepts
decreases only — anything that is not a strict decrease is refused at quote
time, so no confirmation token is ever minted for it, and clearing the daily cap
counts as a raise and is not expressible at all. Setting a cap where none exists
is allowed; the org's enforcement mode is preserved; even a decrease requires
org-admin. To raise a limit, use the GPU.ai dashboard or the gpu CLI.
Also deliberately absent: there is no tool for image or video generation,
and none that creates a deposit — deposits are readable (gpu_deposits_list,
gpu_deposits_get) because "did my funding arrive" is worth answering, but
initiating a funding movement is a dashboard action.
Tools
Free, read-only (38): gpu_auth_status, gpu_health_get, gpu_types_list,
gpu_pricing_list, gpu_instances_list, gpu_instances_get,
gpu_operations_get, gpu_ssh_keys_list, gpu_ssh_keys_get, gpu_usage_get,
gpu_templates_list, gpu_templates_get, gpu_environments_list,
gpu_models_list, gpu_models_get, gpu_fine_tuning_get,
gpu_fine_tuning_list, gpu_fine_tuning_events_list, gpu_webhooks_list,
gpu_webhooks_get, gpu_watch_list, gpu_watch_get, gpu_autolaunch_list,
gpu_autolaunch_get, gpu_market_history,
gpu_spending_limit_get, gpu_balance_get, gpu_deposits_list, gpu_deposits_get,
gpu_instances_gpu_suggestion, gpu_jobs_list, gpu_jobs_gpu_types, gpu_jobs_get, gpu_jobs_logs,
gpu_functions_list, gpu_functions_get, gpu_function_runs_list,
gpu_function_runs_get.
gpu_instances_get and gpu_instances_list carry two fields worth knowing.
gpuMemory is the highest GPU memory the instance has used since launch, and
gpu_instances_gpu_suggestion uses it to say whether a cheaper GPU model would
have fit. bootPhase is present while an instance is allocating or starting
and says how far the launch has got (machine_requested, pulling_image, or
setting_up), so an agent can tell a slow launch from a stuck one.
gpu_market_history returns GPU.ai's own price and availability for a GPU
model over time. Its result has one property worth restating outside the tool
description: available_count: 0 means we sampled and the market was sold out,
while null means we did not sample that bucket at all. They are different
facts, and reporting a null as a stockout blames supply for a gap in our own
collection.
Writes — single confirmation (12): gpu_ssh_keys_create,
gpu_ssh_keys_delete, gpu_webhooks_create, gpu_webhooks_delete,
gpu_instances_update, gpu_fine_tuning_cancel, gpu_spending_limit_update,
gpu_watch_create, gpu_watch_delete, gpu_autolaunch_cancel, gpu_jobs_cancel,
gpu_function_runs_cancel.
Watch rules are the notify-only half of GPU Market: they alert when a GPU
model's price drops below a number you set, or when it comes back in stock.
They are write-tier because they make the account send mail, and they can never
spend — no parameter on gpu_watch_create launches anything.
Auto-launch rules are the spending half, and they are a separate resource
with a separate tool per operation: gpu_autolaunch_create is money-tier (it
pre-approves a bounded, unattended purchase), gpu_autolaunch_cancel is
write-tier, and the two reads are free. The split is deliberate and mirrors the
API's own scopes: creating a rule needs autolaunch:write, which is granted
only explicitly and is not covered by full_access or standard, while
listing and cancelling need only autolaunch:read. Withdrawing a standing spend
authorization is never made harder than granting one. There is no tool that
converts a watch rule into an auto-launch rule, and no tool that makes an armed
rule fire — a rule fires by itself, in the background, with no confirmation at
that moment, which is why the confirmation happens at creation.
Money (8): gpu_instances_create, gpu_instances_deploy,
gpu_fine_tuning_create, gpu_instances_terminate, gpu_autolaunch_create,
gpu_jobs_submit, gpu_function_runs_create, gpu_chat_completion.
gpu_jobs_submit queues a batch job, which is a container image and a command.
A job can start a machine in your organization's job pool, so it is a money
tool. Its quote is the cheapest current single GPU listing and about what one
attempt can cost. The platform caps a job machine at a fair-price multiple of
the cheapest offer the job pool can use, and max_price_per_hour sets a hard
ceiling. It requires gpu_type. Jobs are not enabled on every account, and a
404 from a job tool means they are not available yet.
gpu_function_runs_create calls a deployed function with JSON arguments, which
the server pickles as plain Python values. It is a money tool because a cold
call starts a billed machine. gpu_function_runs_get with include_result
decodes a return value made of plain data, and says so when the value is a
Python object only the SDK can read. Deploying a function needs the Python SDK
(gpuai_sdk.functions) or gpu functions.
Provisioning is asynchronous: a confirmed create or deploy returns an operation
id immediately and never blocks. Poll gpu_operations_get on a 2s→10s backoff
until succeeded, failed or cancelled. Billing runs until
gpu_instances_terminate succeeds — nothing stops on its own. Fine-tuning jobs
are the exception: they carry their own status and are polled with
gpu_fine_tuning_get.
A confirmed create or deploy can also return jobs_hint. The API sends it when
the request is a one-off batch run, or when the organization launched many
instances in the last 24 hours that each ran for less than 15 minutes. It says
that gpu_jobs_submit runs that kind of work without a machine per task.
Per-tool detail, parameters, and the full setup guide are at https://gpu.ai/docs/mcp.
Support
Email [email protected].
License
Apache-2.0
