CloudGPU MCP

CloudGPU MCP

CloudGPU MCP server: let an AI agent compare GPU compute costs, approve source-specific billing, run a job, bring the results back and shut the GPU down. The same API key and balance also cover CloudGPU's OpenAI-compatible model API, so an agent can call a hosted model without renting anything.

"Fine-tune a 7B base model with LoRA on data/train.jsonl and put the adapter in ./outputs."

The agent checks live prices and quotes you, rents the GPU once you say yes, uploads your code and data, starts training in the background, watches the logs, downloads the adapter and destroys the instance. You get the files and the final cost.

It is a local (stdio) MCP server. It works with any MCP client that can start one: Claude Code, Cursor, Cline, opencode, goose, VS Code, Windsurf and others.

Install

For the browser-approval flow, add this local MCP server without an API key first:

claude mcp add cloudgpu -- npx -y cloudgpu-mcp

For another stdio client, use command: "npx" and args: ["-y", "cloudgpu-mcp"]; omit the environment key. Ask the Agent to call connect_account, open its returned CloudGPU link yourself, approve the account, spending limit, GPU concurrency and expiry, then let it call finish_connect. Never paste your password or API key into the conversation. The client must support and configure MCP; the approval link alone does not install tools in an arbitrary assistant. Existing API-key setup remains available below.

1. Create an API key at cloudgpu.app/api and add a prepaid balance (card or USDT).
2. Add the server to your client. Node.js 18 or newer is required. The key goes in the environment variable CLOUDGPU_API_KEY.

Claude Code

claude mcp add cloudgpu --env CLOUDGPU_API_KEY='<YOUR_API_KEY>' -- npx -y cloudgpu-mcp

Cursor ( ~/.cursor/mcp.json or .cursor/mcp.json )

{

"mcpServers": { "cloudgpu": { "command": "npx", "args": ["-y", "cloudgpu-mcp"], "env": { "CLOUDGPU_API_KEY": " " } } } }

</details>

Cline (MCP Servers → Configure MCP Servers → cline_mcp_settings.json )

{

"mcpServers": { "cloudgpu": { "command": "npx", "args": ["-y", "cloudgpu-mcp"], "env": { "CLOUDGPU_API_KEY": " " } } } }

</details>

opencode ( opencode.json )

{

"$schema": "https://opencode.ai/config.json", "mcp": { "cloudgpu": { "type": "local", "command": ["npx", "-y", "cloudgpu-mcp"], "environment": { "CLOUDGPU_API_KEY": " " }, "enabled": true } } }

</details>

goose ( ~/.config/goose/config.yaml , or goose configure → Add Extension → Command-line Extension)

extensions:

cloudgpu: name: cloudgpu type: stdio cmd: npx args: ["-y", "cloudgpu-mcp"] envs: CLOUDGPU_API_KEY: " " enabled: true timeout: 300

</details>

1. Optional but recommended: copy rules/cloudgpu.md into your project as AGENTS.md, .cursor/rules/cloudgpu.md or .clinerules/cloudgpu.md. It tells the agent to quote before renting, download before shutting down, and never leave a GPU running. The server also exposes the same text as the resource cloudgpu://rules.

To check the install, ask your agent: "List the GPUs available, then estimate the cost for a 24 GB GPU for one hour. Do not create anything." You should see list_gpus and estimate_cost calls and a quote, and nothing is rented.

Agent Skill

The same guidance is available as two Agent Skills:

• skills/cloudgpu/SKILL.md: renting and using a GPU. Claude Code loads it on demand when you ask for a GPU job. It expects the cloudgpu MCP tools to be installed (see above).
• skills/cloudgpu-model-api/SKILL.md: calling the OpenAI-compatible model API at https://cloudgpu.app/v1 without renting a GPU. It works with the MCP tools or with just a CLOUDGPU_API_KEY.

• Claude plugin: both skills are included automatically when you install the CloudGPU Claude plugin from this repo's marketplace:

  /plugin marketplace add cloudgpu-app/cloudgpu-mcp

/plugin install cloudgpu@cloudgpu

• Codex plugin: the same repository is an Agent Plugins package (plugin.json, mcp.json, and skills/). Codex shows it as CloudGPU. The server reads CLOUDGPU_API_KEY from the environment.

  codex plugin marketplace add cloudgpu-app/cloudgpu-mcp

• Claude Code, personal install: copy skills/cloudgpu/ and skills/cloudgpu-model-api/ to ~/.claude/skills/.
• Claude Code, project install: copy skills/cloudgpu/ and skills/cloudgpu-model-api/ to .claude/skills/ in your project.
• Cursor, Codex, Cline, Amp and other agents that read Agent Skills: install both skills with the skills CLI:

  npx skills add cloudgpu-app/cloudgpu-mcp

Tools

The server also provides a train_on_cloudgpu prompt.

Guardrails

• A quote first. create_instance only takes a quote_id from estimate_cost and user_confirmed=true.
• Server-side limits. Every instance is created with max_spend_usd, max_hours and an idle limit (60 minutes by default). CloudGPU's servers check them and destroy the instance when one is hit, even if your client has disconnected or your laptop is asleep.
• Your own ceiling. CLOUDGPU_MAX_SPEND_USD and CLOUDGPU_MAX_HOURS cap what the agent may set.
• Results before shutdown. After commands have run, stop_instance refuses until something has been downloaded, unless the user confirms force=true.
• Secrets stay out of the chat. The instance's SSH login is used inside this process and never returned to the model. Tool output is scrubbed of the API key and login details. Uploading .ssh, .env, key files or your whole home directory needs allow_sensitive=true.
• The instance stays manageable. Commands that change the root password, SSH configuration, firewall or the platform's monitoring agent are refused. CloudGPU shuts down instances that it can no longer monitor.
• Jobs are not started twice. run_job sends an Idempotency-Key. Resending the same job returns the same job instead of starting a second GPU, and the server refuses the same key with different parameters.
• Keys with a budget. A key from connect_account has a total spending limit, a number of GPUs it may run at once and an expiry date, all enforced by CloudGPU's servers. Revoke it at https://cloudgpu.app/api and it can no longer start anything.
• Read-only mode. CLOUDGPU_READ_ONLY=1 registers only the look-up tools.

Configuration

Model API on the same balance

The key also works with the OpenAI-compatible API at https://cloudgpu.app/v1. Call list_models (or GET /v1/models) to see the available model IDs. Model prices are on cloudgpu.app/api.

Optional persistent files and Workspaces

These tools require persistent storage to be explicitly enabled on the server; they return storage_not_enabled until it is ready. Discover server capabilities at /v1/public/compute-capabilities. Read get_storage for current included allowance, quota, prices and retention. Storage fees are separate from GPU Job budgets. Uploads above the included allowance require accept_storage_charges=true after user agreement; the default is false. Budget-limited connect-link keys cannot enable paid storage. Files expose expires_at; downloading does not renew retention. Versions containing expired files become unavailable, while active Jobs defer deletion.

• get_compute_catalog and quote_compute use public discovery and server quotes, including required starting balance and supports_jobs. Pass the server quote to run_job as quote_id; the original estimate_cost remains a local quote for interactive instance rentals.
• get_storage, list_files, list_workspaces, list_workspace_versions and get_workspace_version show saved files, versions and usage.
• upload_artifact and download_artifact transfer persistent files, including datasets/models, without returning storage credentials to the assistant.
• save_workspace saves regular project files as an immutable version. It refuses known credential paths and symlinks, and skips .git, node_modules, __pycache__ and .venv. Save dependency manifests so the next GPU can rebuild its environment. The returned workspace_version_id can be passed to run_job.
• delete_file and delete_workspace_version require explicit user confirmation and refuse active references.

This restores project files into a fresh directory before the Job command. It is not full-disk restore and does not automatically save edits or collect outputs. Continue saving results from the command itself. Large-model restore speed and cross-supplier cache behavior must be measu