CloudGPU MCP: connect an Agent to GPU compute
CloudGPU provides remote MCP with OAuth and a local stdio package. Use a configured MCP-capable client to check task fit, review a source-specific quote and approve bounded GPU work. Connecting an account or adding funds does not approve a paid task.
Connect through remote MCP (OAuth)
- In a client supporting remote Streamable HTTP and OAuth, configure
https://cloudgpu.app/mcpas the server URL. This route is the protocol endpoint, not the documentation page. - Complete the client’s browser authorization. Sign in with Google or email, check the selected account, balance, scopes and spending limits. Add funds on the owner page when needed, then approve only the intended access.
- Return to the client and check available tools. Start with the anonymous self-check and task evidence. Local and remote tool sets differ: remote orchestration does not read your local files or provide local SSH transfers.
- Review the task, exact quote, minimum charge, billing period, GPU budget/runtime and any storage fees before execution. Some sources charge by the minute; whole-hour sources charge every started hour in full and do not refund unused time in a charged hour on voluntary stop.
ChatGPT or Claude users need a client/account/workspace configuration that supports remote MCP connectors and OAuth. Availability varies by client and plan; this is not a claim of a public connector-directory listing or endorsement. An ordinary chat or an account-approval link alone does not install tools. Consult the client’s current connector instructions if its settings do not offer a remote server URL.
For Codex with remote MCP support:
codex mcp add cloudgpu --url https://cloudgpu.app/mcp
codex mcp login cloudgpu
OAuth discovery: protected resource and authorization server. No API key should be pasted into chat.
Connect a local stdio client
Local stdio needs Node.js 18 or newer and can access files on the computer running it. Add it without a key, then ask it to call connect_account, open its returned link yourself, approve the account and limits, and call finish_connect. If needed, local tools request_top_up and wait_for_funds create a human payment link and check credited balance; they do not pay for the owner. Pending approval survives a local restart until expiry.
codex mcp add cloudgpu -- npx -y cloudgpu-mcp
Existing keys can still be configured through a client’s secure environment mechanism as CLOUDGPU_API_KEY. Never put a real key in a conversation or shared source file. Client-specific examples follow.
Building a direct HTTPS agent? Use the REST integration guide, machine-readable contract and Agent overview.
Cursor (~/.cursor/mcp.json), Windsurf, Cline (MCP Servers → Configure), Claude Desktop:
{
"mcpServers": {
"cloudgpu": {
"command": "npx",
"args": ["-y", "cloudgpu-mcp"]
}
}
}
Claude Code:
claude mcp add cloudgpu -- npx -y cloudgpu-mcp
opencode (opencode.json):
{
"mcp": {
"cloudgpu": {
"type": "local",
"command": ["npx", "-y", "cloudgpu-mcp"]
}
}
}
VS Code (.vscode/mcp.json):
{
"servers": {
"cloudgpu": {
"command": "npx",
"args": ["-y", "cloudgpu-mcp"]
}
}
}
- Optional: copy the agent rules file into your project as
AGENTS.mdor.cursor/rules/cloudgpu.md, or wherever your assistant reads project instructions. It tells the assistant to quote before renting, download before shutting down, and never leave a GPU running.
What the assistant can do
| Tool | What it does |
|---|---|
get_account |
Balance, and how many instances the account may run at once |
list_gpus |
GPU models with VRAM, live price per GPU-hour and availability |
list_templates |
Ready-made images such as JupyterLab, Ollama, ComfyUI and LLaMA-Factory |
estimate_cost |
Live quote for a GPU and a number of hours, plus your balance afterwards |
create_instance |
Rents the GPU from a quote the user approved, with a budget and a time limit |
get_status / list_instances |
Status, minutes run, cost so far, auto-shutdown limits |
run_command |
Runs a command on the instance; long jobs run in the background |
tail_logs |
Latest log lines, whether the job finished, GPU utilisation |
upload / download |
Copies files and folders between your computer and the instance |
stop_instance |
Destroys the instance and stops billing |
list_models |
Models on the OpenAI-compatible API, if you only need inference |
run_job |
Runs one command on a GPU from start to finish on CloudGPU’s servers; retrying it never starts a second GPU |
get_job / list_jobs / cancel_job |
Job status, exit code, cost and output; cancel destroys the job’s GPU |
connect_account / finish_connect |
Gets the assistant its own key: you approve it in the browser with a spending limit, and the key is saved on your computer |
get_compute_catalog / quote_compute |
Discover compute capabilities and request a quote |
request_top_up |
Creates a short-lived link only. No checkout, card charge or transfer is made. Show the link to the human owner; never complete payment for them. Payment completion does not approve a GPU quote. |
wait_for_funds |
Read-only polling of actual account balance and real-top-up signal for up to 60 seconds. No payment, job submission or authorization. If still pending, return to the owner; do not blindly repeat rentals. |
get_agent_readiness |
No login or spending: capabilities, source-specific billing, task prerequisites, limitations, recent aggregate Job evidence and known issues. Unknown data is not a healthy or verified result. |
assess_task_fit |
Read-only task suitability before quoting a GPU. Returns blockers, unverified requirements and evidence status; does not benchmark, approve spending or guarantee availability. |
quote_storage_budget |
Quote reserving GPU wallet funds for persistent storage, or returning unused surplus. No transfer yet. Shows USD rate, budget-based capacity and 30-day file expiry. Budget-limited keys cannot move funds; ask owner to use Web or unrestricted key. |
confirm_storage_budget |
Moves wallet funds only after the user approves the exact quote. Retrying the same quote cannot transfer twice. Reservation is not billed usage; daily actual peak consumes the budget. Never approve automatically. |
resume_artifact_upload |
Resume the same unexpired multipart reservation. Requires the original SHA-256 reported when upload paused. Skips completed parts; renews expiring URLs. Never mixes changed files or creates another reservation. |
get_storage |
Storage eligibility, usage, reserved uploads, quota, retention and charges |
list_files |
List persistent files |
upload_artifact / download_artifact |
Upload to persistent storage or download a saved file to this computer |
delete_file |
Delete a saved file after user confirmation |
list_workspaces |
List saved Workspaces |
save_workspace |
Save local project files as an immutable Workspace version |
list_workspace_versions / get_workspace_version |
List versions and read a version’s file manifest |
list_workspace_instances |
List your running GPUs accessible to this key |
apply_workspace / get_workspace_application |
Apply a saved version to a running GPU after confirmation; check restore status |
delete_workspace_version |
Delete a version after user confirmation |
list_task_templates |
Discover local task drafts; no network or GPU allocation |
prepare_task_template |
Prepare command/Workspace/result fields; quote and explicit budget/time approval still required |
prepare_job_batch |
Review an immutable batch and aggregate GPU cap locally; no submission |
run_job_batch |
Submit approved Jobs with stable keys; partial acceptance is possible, no automatic execution retry |
get_job_batch |
Read status and costs for explicit Job IDs; no resource changes |
get_job_batch_receipt |
Read private local accepted IDs and uncertain intents for the original key/endpoint; historical, not live status |
diagnose_job |
Read-only failure/cost diagnosis; never retries or changes GPU resources |
save_job_output |
With explicit approval, save an ended Job log tail as a small Artifact; not full output collection |
resolve_model_reference |
Pin public model files to a commit, sizes and available checksums without hosting weights |
prepare_model_deployment |
Prepare a reviewed ComfyUI model/workflow setup script; starts no GPU and executes no graph |
prepare_job_rerun |
Read successful Job parameters; obtain a fresh quote, approval and new key before running again |
upload and download transfer files directly between this computer and a GPU; they do not save files in Workspace. Use upload_artifact / download_artifact for persistent files. run_job accepts workspace_version_id to restore a version before executing its command.
Read get_storage before saving: eligibility, quota, retention and charges depend on the account. Paid storage requires explicit user consent; budgeted Agent keys cannot opt into paid storage. Applying a Workspace requires confirmation, writes into a separate project directory, and does not stop or restart the GPU, overwrite existing project files, or install dependencies. Budgeted Agent keys can apply only to instances created by that same key. Check get_workspace_application before retrying an uncertain restore. Full-disk backup is not provided. Optional Job output collection requires automatic_output_collection=true; declare explicit outputs and inspect output_collection. Saving can fail and still releases the GPU; there is no automatic rerun.
Guardrails
- A quote first.
create_instanceonly accepts aquote_idfromestimate_cost, plus confirmation that the user approved it. The assistant sees the live price, the estimate and the balance after the job before anything is rented. - Limits our servers enforce. Every instance the MCP server rents carries
max_spend_usd,max_hoursand, by default, a 60-minute idle limit. CloudGPU checks them every minute and destroys the instance when one is reached, whether or not your client is still connected. - Jobs are not started twice.
run_jobsends an idempotency key, so a retried request returns the same job instead of starting another GPU. - A key with a budget. A key from
connect_accounthas a total spending limit, a number of jobs or instances it may run at once and an expiry date, enforced by CloudGPU’s servers. Revoke it on the API page at any time. - Your own ceiling.
CLOUDGPU_MAX_SPEND_USD(default 50) andCLOUDGPU_MAX_HOURS(default 24) cap what the assistant may set.CLOUDGPU_READ_ONLY=1leaves only the look-up tools. - Results before shutdown. If commands were run and nothing was downloaded,
stop_instancerefuses until the assistant downloads the results or you confirm. - Secrets stay out of the chat. The server uses the instance’s SSH login itself and never returns it to the model. Output is scrubbed of the API key and login details, and uploading
.ssh,.envor key files needs explicit permission. - The instance stays manageable. Commands that change the root password, the SSH configuration, the firewall or the platform’s monitoring agent are refused. Instances must stay reachable for monitoring, as stated in the acceptable use policy.
The REST API underneath
The MCP server is a thin wrapper around the public GPU API (/v1/gpu/offers, /v1/gpu/instances, /v1/jobs and so on), which every account can use with the same key. The agent guide describes jobs and connect links. Agents and scripts that don’t speak MCP can call it directly, and the auto-shutdown fields max_minutes, max_spend_usd and idle_minutes work the same way there.
FAQ
Do I need a separate account or key for the MCP server?
No. It uses a normal CloudGPU API key, and GPU time comes out of the same prepaid balance as the model API.
What happens if my laptop sleeps during a long training run?
The job keeps running on the instance. The budget and time limit you approved still apply, because CloudGPU’s servers enforce them. When you come back, the assistant can check the logs and download the results.
Can the assistant spend more than I approved?
Review and approve a source-bound billing quote and GPU spending/runtime limits. CloudGPU enforces instance and scoped-key limits; local stdio can additionally enforce CLOUDGPU_MAX_SPEND_USD. The source minimum must fit the approved budget. Separately approved storage charges are not included in the GPU cap.
Which clients work?
Clients supporting remote Streamable HTTP and OAuth can use https://cloudgpu.app/mcp; connector availability depends on client, account and workspace policy. Local stdio clients include Codex, Cursor, Cline, opencode, Claude Code, Continue, Windsurf, VS Code and Claude Desktop. The local and remote tool sets differ.
Is the source available?
Yes. It is MIT-licensed at github.com/cloudgpu-app/cloudgpu-mcp.
Save selected Job results
With MCP 0.9.0 and live automatic_output_collection=true, run_job accepts outputs: {"files":["metrics.json"],"max_bytes":1048576}. Write the result to "$CLOUDGPU_OUTPUT_DIR/metrics.json". This saves only the named files, not a directory or disk image. Read get_job.output_collection: only succeeded confirms all requested files were saved; download ready file_id values with existing file tools. Cancellation, budget exhaustion and transfer errors can prevent saving. Transfer time uses the same GPU limits; storage follows your existing quota, retention and charges. Budget-limited Agent keys use included storage only.
A remote MCP session does not have the local stdio file tools. Do not pass an instance path to save_workspace or upload_artifact. The parameter walkthrough is How to save GPU results over remote MCP.
The separate save_job_output tool saves only a log tail. Version 0.8.0 still has a credential-filter gap; use 0.9.0 or later and only explicitly sanitized logs. The filter rejects recognizable patterns and common escapes, but cannot guarantee that arbitrary log contents are secret-free.
Your first task: prepare, then approve
MCP 0.11.0 includes local read-only recipe tools. Ask your Agent to call list_task_templates, then prepare_task_template for gpu-check, csv-summary or workspace-python. Preparation never rents a GPU, installs dependencies or charges you. Prefer a local CPU for CSV-only processing. Your own Python task needs an immutable Workspace version and a reviewed script with dependencies prepared separately. Keep using prepare_model_deployment for ComfyUI preparation; complete ComfyUI and LoRA batch recipes are not certified by this release.
The draft omits GPU selection, quote, budget, time limit, approval and idempotency key. The Agent checks live capabilities and obtains a quote, then calls run_job only after your explicit approval. Persistent results are optional; storage-fee consent defaults to false and existing eligibility, quota, retention and charges apply. Failed tasks are not automatically retried.
Experimental application recipes and bounded batches
MCP 0.11.0 adds comfyui-workflow for an API-format workflow on an already prepared ComfyUI GPU image, and causal-lm-lora for a small causal-language-model adapter. The latter is not image/SDXL LoRA training. Both require an immutable Workspace and explicit persistent result collection. They do not install dependencies, start application servers or infer storage-charge consent. Model files use the existing pinned-reference download path. Local protocol/orchestration fixtures are not real GPU generation, training quality or universal image compatibility acceptance.
For a batch, obtain fresh per-Job quotes and set each task’s GPU budget and time limit. prepare_job_batch checks up to eight Jobs and that the sum of their GPU spending caps fits total_budget_usd; separately approved storage charges are additional. Present all tasks and costs to the user. Only after approval, call run_job_batch with the identical manifest, returned approved_plan_sha256, stable caller-retained batch_key and user_confirmed=true.
Retain the receipt and manifest. Partial submission can occur. On a lost response, reconcile or replay only the identical approved manifest/key; existing Job idempotency prevents replacement GPUs. Do not silently change expired quotes or use new keys for uncertain submissions. get_job_batch reports status and costs, without claiming independent supplier release. The legacy client tool has no automatic failed-execution retries or durable batch-level scheduler; accepted Jobs use the existing backend queue, while unsubmitted members do not continue after a client exit.
Recover a local batch receipt after restarting the client (MCP 0.12.1)
Use 0.12.1 or later: it synchronizes newly created receipt directory entries before paid submission and refuses submission if synchronization fails. Keep existing receipts and the original manifest when upgrading. Process restart tests do not certify recovery from physical power loss.
Call get_job_batch_receipt with the original batch_key on the same device, scoped key and API endpoint, then use get_job_batch for live status. Replaying the identical approved manifest queries known Jobs; an uncertain acknowledgement is reconciled with the original request/key. Unavailable status, release uncertainty or a terminal Job without final settlement stops further submissions. An in-flight batch keeps its original credential even if another tool connects a different account.
Receipts contain private metadata only, not commands, keys, signed links or the full manifest. Keep the exact reviewed manifest separately. Missing local records do not prove non-creation; unvisited entries in a call may already exist from an earlier call. Local receipt or write failures stop paid batch progress; if acceptance was known, the returned Job ID is retained. Private permissions, no-follow opens and atomic file links must be supported. New entries are refused once the default 1,024-directory threshold is observed; archive verified terminal records explicitly, retain uncertain ones.
This is local durability, not a server batch coordinator. Unsubmitted members do not run after client exit and failed executions are not automatically retried. Expired quotes may require reconciliation and a newly reviewed plan for remaining work. GPU and storage approvals remain separate. The original single-Job flow is unchanged.
Machine-readable task contract
Canonical rules: https://cloudgpu.app/agent-contract.json . Anonymous self-check: https://cloudgpu.app/v1/public/agent-self-check . Evidence with measured costs and incomplete cases: https://cloudgpu.app/agent-evidence.json . Inspect runtime capabilities before relying on remote MCP, storage budgets or URL renewal. Remote orchestration tools do not access a local filesystem or provide SSH file-transfer tools.
Durable server batches and whole-hour Jobs
Use MCP 0.16.3 prepare_job_batch → approve the exact manifest/hash and aggregate budget → run_server_job_batch. Atomic enqueue persists every child Job or none; the database queue continues after client/server restarts and waits for account/Key execution slots. Use get_server_job_batch and approved cancel_server_job_batch. Failed commands are not automatically retried; unknown creation results require reconciliation. The older run_job_batch remains a non-atomic client flow.
REST: POST /v1/job-batches with one stable Idempotency-Key, total_budget_usd and 1–32 jobs; GET /v1/job-batches/{batch_id}; POST /v1/job-batches/{batch_id}/cancel. The reviewed MCP manifest is capped at eight Jobs. Batch responses contain bounded summaries; use get_job for explicit output metadata. Each child keeps its own spending/time limits; storage fees remain separate.
Whole-hour Jobs require the exact rental billing quote (estimate_cost / POST /v1/gpu/billing-quote) and explicit billing_quote_id, billing_accepted=true, plus the compute quote and execution approval. Every allocation needs its own billing quote. Budget must cover the minimum; each started hour is charged in full. Quotes expire after five minutes: expired queued requests fail without allocation and need a newly reviewed request. The service never silently changes the approved billing terms. Linked running Jobs resume through existing recovery; durable receipt aliases plus independent provider presence checks protect whole-hour reconciliation. Ambiguous intents remain needs_attention; they never authorize another GPU.