How to save GPU results over remote MCP

Stopping billing does not keep files. stop_instance and instance termination erase the local instance disk, and a Job releases its GPU when it ends. Remote MCP does not provide local SSH or client-filesystem upload and download. A result remains only after the command wrote the named files under $CLOUDGPU_OUTPUT_DIR, collection status is succeeded, or the file was already stored through a tool the current remote session actually lists — and only after that status or file is confirmed.

Read the remote tool list first

The owner authorizes the remote Streamable HTTP endpoint https://cloudgpu.app/mcp. Setup is in the MCP guide. After authorization, use the tool list that session returns. Do not assume the local stdio inventory from cloudgpu-mcp 0.16.3.

The MCP guide says remote orchestration does not read local files or provide local SSH transfers. The published package README says the remote endpoint exposes the tools that do not need a local filesystem or SSH. If a name below is missing from the session list, skip it. Do not invent a replacement.

Preconditions

  1. Read GET /v1/public/compute-capabilities. Collection applies only when automatic_output_collection is true. full_disk_restore false means Workspace is not a disk image.
  2. Read storage terms with get_storage when it is listed. Otherwise use authenticated GET /v1/storage. Eligibility, quota, retention, and charges are separate from GPU spend. A GPU approval is not storage approval.
  3. Leave accept_storage_charges false unless the owner has agreed to paid storage. A budget-limited agent key cannot consent to paid storage. quote_storage_budget and confirm_storage_budget, when listed, move wallet funds only after a separate owner approval. They are not part of max_spend_usd.

Collect Job outputs

Use this when run_job and get_job are on the remote tool list. run_job runs on CloudGPU’s servers. It does not take a client-local path.

  1. Show the owner the quote, the command, the output names, max_spend_usd, and max_hours. Set user_confirmed to true only after they approve that request.
  2. Pass outputs exactly as an object of relative file names. The documented shape is files, optional max_bytes, and optional accept_storage_charges. No globs. The published schema allows 1–16 names, a default total of 10 MiB, and a maximum of 100 MiB. The MCP guide example is:
{"files":["metrics.json"],"max_bytes":1048576,"accept_storage_charges":false}
  1. The Job command must create those files under $CLOUDGPU_OUTPUT_DIR and nowhere else the collector should read. For the example name, the command writes $CLOUDGPU_OUTPUT_DIR/metrics.json. Paths are relative to that directory. Hidden names, credential names, symlinks, and hard links are refused.
  2. Keep the returned job_id and the idempotency_key you sent. A lost response is retried with the same key and the same body. A new key is a new Job.
  3. Pass quote_id from quote_compute when that tool is listed. For a whole-hour source, also pass the current billing_quote_id and billing_accepted true, as the MCP guide describes. This page does not restate billing rules. The pricing page is the billing source.
  4. Optional workspace_version_id restores an already saved version into a fresh project directory before the command. It does not save new files and does not restore installed dependencies.

persist_results is a flag on the local tools prepare_task_template and prepare_task_pipeline. It is not a run_job field. Those preparation tools are local and are not a remote MCP step.

Do not pass an instance path to local file tools

These cloudgpu-mcp 0.16.3 tools take a path on the computer running local stdio. Do not call them from remote MCP with an instance path, including $CLOUDGPU_OUTPUT_DIR or a remote directory:

Tool Local stdio parameter Why it is not a remote instance path
save_workspace local_dir Reads a client directory and saves an immutable version
upload_artifact local_path Uploads one client file
download_artifact file_id and local_path Writes the file onto the client computer
resume_artifact_upload local_path Resumes a client file
upload / download client local_path and instance remote_path SSH transfer from the local stdio process

run_command and tail_logs in that package also use the local SSH session. Do not assume they are on the remote list. The official docs do not provide a remote MCP tool that copies an arbitrary instance path to the MCP client.

If a Workspace version already exists, and apply_workspace is listed, call it with version_id, instance_id, and user_confirmed true, then read get_workspace_application with the same version_id and instance_id. That copies the saved files into a new project directory. It does not install dependencies, overwrite existing files, or restore the operating system. The owner can create the version in the web Workspace UI, described in the agent guide. The official docs do not provide a remote MCP tool that saves the instance disk as a new Workspace version.

Reuse is not the same as keeping files

Running more approved work on the same instance_id uses that rental only while it is still running. It does not keep files after stop. run_job provisions a GPU and releases it when the command ends. prepare_job_rerun, when listed, reads parameters from a successful Job. It does not start a GPU, and it does not reuse the old quote or the old idempotency key. A Workspace version reuses the selected project files, not the operating system or installed dependencies.

Confirm the save, then release

  1. Call get_job with the original job_id. Read output_collection. Only status succeeded means every requested file was saved. A saved entry has file_id, sha256, size_bytes, and status ready. The log tail on get_job is about the last 4 KB of command output. It is not the collected file.
  2. If list_files is listed, use it to see the persistent file. It does not copy the file to the MCP client.
  3. download_artifact is the local stdio download. When it is absent, the documented retrieval for a ready file_id is POST /v1/files/{id}/download. The agent guide says that call returns a short-lived URL. Treat the URL as a credential and do not log it. The OpenAPI description says the authorization does not prove the transfer finished. output_collection itself does not include a signed URL.
  4. Confirm the file or succeeded status before stop_instance, and before treating a finished Job as saved. Do not leave an idle GPU running only to consume time that was already authorized.
  5. Keep the original Job or instance id. If the response is lost, poll that id. stopping and needs_attention are not a confirmed release and are not permission to allocate again.

Limits that change the result

Collection can fail and the GPU can still be released. Cancellation, budget exhaustion, and transfer errors can leave output_collection as failed or skipped. Partial files with status ready may remain. That is not overall success, and it does not authorize another Job.

When the GPU cannot reach object storage, the machine-readable contract describes a relay of up to 8 MiB. Direct collection stays within the outputs.max_bytes bound, whose schema maximum is 100 MiB. Larger outputs need a path the live contract marks as available. Do not raise max_spend_usd to stand in for storage.

full_disk_restore is false. Workspace is not a mounted disk and not an automatic backup. Retention and charges come from get_storage or GET /v1/storage. Downloads do not extend expires_at.

Rent, reuse, and release boundaries are in the rent-and-reuse guide. Local stdio Jobs and Workspace are in GPU Jobs for AI agents. SSH, rsync, and Hub uploads from a machine you can reach are in Save your work before you destroy a cloud GPU. Project reuse is in the project reuse example. Tool rules are in AGENTS.md.

Questions and answers

Does stopping the GPU keep the files?

No. stop_instance and instance termination erase the local instance disk. A Job releases its GPU when it ends, including when output collection fails. Files remain only when output_collection status is succeeded, or when an earlier explicit save is already in persistent storage under the account quota, retention, and charges.

Can remote MCP copy files off the instance?

No. Remote MCP does not provide local SSH transfers. In cloudgpu-mcp 0.16.3, upload and download are local stdio tools that take a client-local path and an instance path. download_artifact takes file_id plus a client-local local_path. Do not pass an instance path to those tools. For a collected file, call POST /v1/files/{id}/download and do not log the short-lived URL.

Does a GPU spend cap pay for storage?

No. max_spend_usd bounds GPU spend for that Job or instance. Storage has its own eligibility, quota, retention, and charges. Read get_storage or authenticated GET /v1/storage. Leave accept_storage_charges false unless the owner agrees. A budget-limited agent key cannot consent to paid storage.

How do I confirm that collection finished?

Call get_job with the original job_id and read output_collection. Only status succeeded means every requested file was saved. A ready entry has file_id, sha256, size_bytes, and status ready. The log tail is not the file. If the response was lost, poll that same Job id. Do not submit a new idempotency key.