How to run a GPU Job over remote MCP
An MCP client should first check whether a compatible running rental can do the work inside the original caps. If a one-shot command is the right path instead, request a fresh Job compute quote, wait for the owner to approve that quote, submit run_job with a retained idempotency key, and poll get_job until the Job is succeeded, failed, or cancelled. A lost submit does not authorize another Job: keep the original quote id, idempotency key, and any job_id and reconcile those ids instead of inventing a new key, then persist outputs and follow today’s Job-versus-instance cleanup rule, which does not use stop_instance to finish that Job.
The copyable reuse check is How to reuse a running GPU over remote MCP. Cap fields, key limits, and quote clocks are in How to set GPU budget caps over remote MCP. Keeping files is How to save GPU results over remote MCP. Release evidence is in How to stop a GPU and verify release over remote MCP. The pricing page is the billing source.
Preconditions
The owner authorizes the MCP connection first. Remote Streamable HTTP is https://cloudgpu.app/mcp. Local stdio is the published cloudgpu-mcp 0.16.3 package. Setup is in the MCP guide. After authorization, read the tool list that session returns. Local and remote tool sets differ.
https://cloudgpu.app/.well-known/mcp.json lists the stdio inventory and says the remote tool set excludes local filesystem and SSH. The published server card sets the remote tool count at 23. Those 23 names are not published. An unauthenticated POST https://cloudgpu.app/mcp returns 401 invalid_token, so the session list is the list to use. If a name below is missing from the current session list, skip it and use the documented REST path, or another tool that session actually lists. Do not invent a remote-only command or SSH tool.
connect_account and finish_connect, when listed, are the local stdio key flow. That wording is in the budget-caps guide and the MCP guide. Connecting an account is not approval of a quote.
On 2026-11-15, GET /v1/public/compute-capabilities reported jobs true, job_rerun true, storage true, automatic_output_collection true, and full_disk_restore false. Read that document again before relying on Job output collection.
Choose a Job or a standing rental
Call get_account and list_instances before a new Job quote. Both take no parameters in cloudgpu-mcp 0.16.3. Then call get_status on a candidate:
{
"instance_id": "<id from list_instances>"
}
If a running rental already has the needed software or files and still has room inside the original caps, continue on that instance_id. The copyable reuse walkthrough is How to reuse a running GPU over remote MCP. Starting a standing rental is How to rent a GPU over remote MCP.
If the work is a one-shot command that should provision, run, and release on its own, continue below. run_job does not take an existing instance_id and does not replace create_instance.
Get a Job quote and wait for approval
Show the owner the quote before any submit. A quote is not permission to start. quote_compute in cloudgpu-mcp 0.16.3 takes estimated_duration_seconds (a positive integer) and max_budget_usd (a positive number). Optional fields are min_vram_gb (integer, default 0), gpu_model, gpu_count (an integer from 1 through 8, default 1), and template. When you pass gpu_model, use the exact string list_gpus returns. Do not copy live prices from that row. The pricing page is the billing source.
{
"estimated_duration_seconds": "<expected seconds, including preparation and the task>",
"max_budget_usd": "<budget the owner set for this quote>",
"min_vram_gb": "<minimum VRAM the task needs>",
"gpu_model": "<full model string from list_gpus, or omit>",
"gpu_count": "<integer from 1 through 8; the schema default is 1>"
}
The tool calls POST /v1/quotes and returns that quote with quote_id set to the quote id. Its description says no GPU is started, and to pass that quote_id to run_job. The 0.16.3 field description says this id starts with quote_. Read supports_jobs on each candidate. The agent guide says that flag is whether this GPU can run a job with POST /v1/jobs right now, and that some GPUs can only be rented as instances. If supports_jobs is false, use the rent guide.
within_budget compares the estimate with max_budget_usd. OpenAPI says that flag does not mean you can start now. Wait for the owner to approve the quote.
estimate_cost returns the local quote_id that create_instance accepts. quote_compute returns the server quote_id that run_job accepts. Pass each id only to the tool that issued it. Do not pass an estimate_cost id to run_job, and do not pass a quote_compute id to create_instance.
Cap fields, key limits, and the quote clocks are in the budget-caps guide. An expired quote does not start a GPU. The agent guide lists 409 quote_expired as “request a new quote”. Get a new quote rather than retrying the old id.
Whole-hour billing quote
For a whole-hour source, the MCP guide and the 0.16.3 run_job schema still require billing_quote_id and billing_accepted true, from estimate_cost or POST /v1/gpu/billing-quote, in addition to the quote_id from quote_compute. Neither quote replaces the other. The owner must accept that billing quote too. Set billing_accepted to true only after that acceptance. Omit billing_quote_id and billing_accepted when the response you just received does not contain billing_quote_id.
The 0.16.3 client refuses the call when billing_quote_id is set and billing_accepted is not true. The refusal text is: “Not started: accept the source-specific minimum charge and billing period first.” What the caps and the minimum mean, and when a quote expires, is in the budget-caps guide. The pricing page is the billing source.
Submit the Job and poll it
Choose an idempotency_key and keep it before the first call. run_job in cloudgpu-mcp 0.16.3 is marked idempotentHint: true. If you omit the key, the client generates one and returns it on the tool result. Keep that returned value. A retry uses the same key and the same body. A new key is a new Job.
The documented REST submit is POST /v1/jobs with a required Idempotency-Key header (a string, maximum 128 characters). The same key and the same request return the existing Job (200, header Idempotent-Replayed: true). A new Job is 202. The same key with a different body is 409 idempotency_key_reused. The agent guide says that key belongs to a different Job: resend the original request unchanged, or use a new key only when the body is a different Job.
When run_job is on the current tool list, pass the approved command, the quote_id from quote_compute, the caps, and the retained key. Set user_confirmed to true only after the owner approves the GPU, the budget, and the time limit. The client refuses the call otherwise. The refusal text is: “Not started: tell the user the GPU, budget and time limit, wait for an explicit yes, then call again with user_confirmed=true.”
{
"quote_id": "<quote_id from quote_compute>",
"billing_quote_id": "<billing_quote_id only when the quote response contains it>",
"billing_accepted": true,
"user_confirmed": true,
"max_spend_usd": "<example budget cap the owner approved>",
"max_hours": "<example hour cap the owner approved>",
"idempotency_key": "<stable key for this submission>",
"command": "<the command the owner approved>"
}
Leave billing_quote_id and billing_accepted out of that body when the response has no billing_quote_id. run_job uses max_spend_usd and max_hours. It does not take idle_minutes. The 0.16.3 client sends max_minutes as the ceiling of max_hours times 60. The MCP input is max_hours. POST /v1/jobs requires command, max_minutes, and max_spend_usd. What those caps mean is in the budget-caps guide.
The client also refuses the call when gpu_model, template, and quote_id are all missing. This page’s path passes the quote_id from quote_compute. The tool description says max_spend_usd and max_hours are enforced by the servers, and that the Job finishes on CloudGPU’s servers even if the MCP client disconnects.
When the command must keep files, add outputs as the save-results guide specifies, and write those files under $CLOUDGPU_OUTPUT_DIR. If the Job uses the official ComfyUI template, the template path is How to run ComfyUI over remote MCP.
Poll get_job with the returned job_id. The run_job result text says to call get_job at intervals, every minute or so, not in a tight loop, until status is succeeded, failed, or cancelled. get_job reads GET /v1/jobs/{id}, the log tail from GET /v1/jobs/{id}/logs (the last ~4 KB), and GET /v1/jobs/{id}/events.
{
"job_id": "<id returned by run_job>"
}
Documented statuses are queued, provisioning, running, stopping, succeeded, failed, cancelled, and needs_attention. The agent guide says queued means accepted, no GPU yet; provisioning means starting the GPU; running means the command is running; stopping means the command finished, or a limit or a cancel was hit, and the GPU is being destroyed; succeeded means the command exited with code 0 and the GPU is destroyed; failed carries error.code; cancelled means the Job was cancelled with POST /v1/jobs/{id}/cancel. needs_attention means CloudGPU could not confirm the GPU state and will not retry the Job automatically. Do not resubmit it with a new key.
failed error.code values named in that table include command_failed, time_limit_reached, spend_limit_reached, insufficient_balance, provisioning_failed, and credential_revoked. Use the fields the response contains, including exit_code, cost_usd, error, and output_collection. Do not fill in api_url or a cost. A Job instance_id is the GPU that Job used. It is not a second rental to destroy.
Lost submit and cancellation
A lost run_job response does not authorize another Job. Keep the original quote id, the idempotency key you retained, and any job_id. Call run_job again only with that same key and the same body, or call get_job when you already have the job_id. When list_jobs is listed, it takes optional limit (integer, default 20, maximum 100) and returns recent Jobs with status and cost. Use it to look for the original Job before any new key. Do not invent a new key to force a second start.
If cancellation is needed, and cancel_job is listed, cloudgpu-mcp 0.16.3 takes job_id only. The tool description says it stops the Job, destroys the GPU if one was started, and stops billing, and that output not yet uploaded by the command is lost. It is marked idempotentHint: true. The REST call is POST /v1/jobs/{id}/cancel. Then read get_job again. stopping and needs_attention are not a confirmed release. A client disconnect does not itself prove that a Job stopped.
{
"job_id": "<the original job id>"
}
402 insufficient_balance means the balance does not cover required_starting_balance. Ask the owner to add funds. Do not retry the submit until it does. request_top_up, when listed, returns a payment link for the owner. Payment is not approval of the quote. 403 key_budget_exceeded and 400 max_spend_required are key-limit results. What the owner does next is in the budget-caps guide.
prepare_job_rerun is not a start
prepare_job_rerun, when listed, takes only job_id. The 0.16.3 description says it reads the original command, pinned model references, and Workspace from a successful Job, does not start a GPU, and does not reuse the old quote or the old idempotency key. A new Job needs a fresh quote and a new approval. The REST read is GET /v1/jobs/{id}/rerun-spec. OpenAPI describes that response as read-only prepared parameters and says no old quote or key is returned.
{
"job_id": "<id of a successful Job>"
}
A batch is a different flow. prepare_job_batch and run_server_job_batch, when listed, are the batch tools. The narrative overview is GPU Jobs for AI agents.
Save results, then release
Persist outputs with the save-results guide. Confirm collection before assuming files are kept. Only output_collection status succeeded means every requested file was saved. save_job_output, when listed, saves a log tail. It is not that collection. Storage charges are separate from GPU caps. Leave accept_storage_charges false unless the owner has agreed to paid storage. That split is in the budget-caps guide and the save-results guide.
Then follow today’s Job-versus-instance cleanup rule and the stop-and-verify guide. run_job starts a GPU, runs one command, and releases that GPU when the command ends. Do not call stop_instance to finish that Job. Status succeeded, failed, or cancelled means the Job is finished. stopping and needs_attention are not a confirmed release. Collection can fail and the GPU can still be released.
Exceptions
Local stdio and remote MCP do not expose the same tools. A quote is not a start. estimate_cost and quote_compute ids are not interchangeable. An expired quote does not start a GPU; get a new quote rather than retrying the old id. A lost submit does not authorize another Job. run_job does not reuse a running instance_id. prepare_job_rerun does not start a GPU. A needs_attention Job is not an automatic retry. Storage charges stay outside the GPU caps. Do not fill in a cost, an api_url, or a file list the response did not return.
Related
Rent, reuse, and release boundaries are in the rent-and-reuse guide. Quotes and Jobs are in GPU Jobs for AI agents and the quote and reuse note. Tool rules are in AGENTS.md. Connection wording is in the MCP guide and the agent guide.
Questions and answers
Should the MCP client start a standing rental instead of a Job?
No. Call get_account and list_instances, and get_status on a candidate, before a new Job quote. If a running rental already has the needed software or files and still has room inside the original caps, continue on that instance_id. A one-shot command that should provision, run, and release on its own uses run_job. run_job does not take an existing instance_id and does not replace create_instance. Starting a standing rental uses create_instance.
Is a quote enough to start the Job?
No. A quote is not permission to start. Wait for the owner to approve that quote, and set user_confirmed to true only after that approval. Pass the quote_compute quote_id to run_job. Do not pass an estimate_cost quote_id to run_job, and do not pass a quote_compute id to create_instance. An expired quote does not start a GPU. Get a new quote rather than retrying the old id. For a whole-hour source, the owner must also accept the billing quote. Pass billing_quote_id only when the response contains it, and set billing_accepted to true only after that acceptance.
What if the run_job response is lost?
Keep the original quote id, idempotency key, and any job_id. Do not invent a new key. Call run_job again only with that same key and the same body, or call get_job when you already have the job_id. list_jobs, when listed, shows recent Jobs on the account. The same key with a different body is 409 idempotency_key_reused. A new key is a new Job.
Does prepare_job_rerun reuse the same GPU or the old quote?
No. prepare_job_rerun takes only job_id. It reads the original command, pinned model references, and Workspace from a successful Job. It does not start a GPU. It does not reuse the old quote or the old idempotency key. A new Job needs a fresh quote and a new approval.