Managing Google Colab Cloud GPUs with Agents (CLI + MCP)

Users want you to start a GPU or TPU on Google Colab for them, run code, deploy or fine-tune open-source models, fetch the results, and then release the machine, without them having to operate the web interface by hand. This Skill combines two official routes and lets you choose based on the scenario:

Route	What it is	Best for
Colab CLI	The official command-line tool google-colab-cli (Apache-2.0), where the local agent calls the colab command	Complex deployments: transferring files, SSH, mounting Google Drive, running a job in one command that releases the machine when done
Colab remote MCP	Google's hosted MCP endpoint https://colaboratory.googleapis.com/mcp (official docs)	Lightweight management: starting a machine, executing code, and shutting down from a chat client, without depending on the local machine

Companion tutorial: Managing Colab cloud GPUs with an agent.

Triggers

User says "run it on Colab", "start a GPU", "deploy/fine-tune this model on Colab", "rent an A100 to run this", "put this script on a cloud GPU", or the local machine lacks compute and a temporary GPU/TPU is needed.

Hard Rules

1. Always release after use. At the end of a CLI session, run colab stop -s <name>; at the end of an MCP session, run delete_runtime. Idle machines keep consuming compute units. For one-off jobs, prefer colab run, which releases automatically when it finishes, including when the script errors.
2. Before starting, state the GPU type and roughly how long it will run. Compute units are the user's money and are deducted by GPU type and duration. Ask first before expensive GPUs (A100, H100).
3. Never pay on the user's behalf. colab pay only opens the subscription page and lets the user decide; do not buy compute units for them.
4. Do not output or log credentials. Auth tokens and Google Cloud credentials stay only in local configuration; do not print them or write them into project files.
5. Do not run interactive commands. colab repl, colab console without piped input, colab auth, and colab drivemount all require a person at the terminal, and running them from the agent will hang. When needed, tell the user to run them.
6. The GPU/TPU may not be available. GPUs and TPUs are granted according to subscription tier and account quota. If one can't be obtained, fall back to T4 or CPU and tell the user why; do not retry repeatedly.
7. Only run models and data the user is entitled to use. Pay attention to open-source model licenses and Colab's terms of service.

Check Quota First

• CLI: colab usage shows the compute unit balance and burn rate.
• MCP: get_subscription returns whether the user is on Free, Pro, or Pro+; list_runtime_specs lists the machine types they can request.
• Users subscribed to a Google AI plan receive Colab compute units monthly according to the plan (official plan page: Plus 50, Pro 200, Ultra 1,000 or 2,000 per month), which are added to the Colab balance. How many hours you get depends on the GPU type; more expensive GPUs deduct more per hour.

Route 1: Colab CLI

Environment

• Only Linux and macOS are supported. Native Windows is not supported; use WSL2 instead.
• The CLI runs on the local machine, so the computer where the agent runs must be on.

Check whether it is installed first:

colab version

If it is not installed, install it with the user's consent:

uv tool install google-colab-cli   # or pip install google-colab-cli

Authentication (the most common point of failure)

The default is ADC (Application Default Credentials), which suits unattended agent use. The user needs to log in once in their own terminal, and all four scopes are required:

gcloud auth application-default login \
  --scopes=openid,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/colaboratory

Verify with colab sessions (read-only). If you hit 401/403, it is almost always wrong credentials or scopes; rerun the login above. Do not have the user run colab auth to fix a 401: that injects GCP credentials into the VM internals and is unrelated to the CLI's own authentication.

Common Workflow

Always include -s <name> when starting a machine; otherwise a random name is generated and later commands may target the wrong machine.

colab new -s job --gpu L4              # optional: T4 / L4 / G4 / H100 / A100; for TPU use --tpu v5e1 / v6e1
colab install -s job torch transformers
colab exec -s job -f infer.py          # reads the local script and sends it to run remotely; no need to upload first
colab download -s job /content/out.txt ./out.txt
colab stop -s job

One-off job (start, execute, release):

colab run --gpu T4 infer.py --model Qwen/Qwen3-8B

Key points:

• Kernel state is preserved within the same session, so variables and imports persist across multiple colab exec calls without reinstalling or reimporting each time.
• The default working directory is /content; use absolute paths for file operations.
• An unrecognized --gpu value silently falls back to A100, and a misspelled GPU name may cost extra, so double-check the spelling.
• colab new with an accelerator returning 400 means the account has no quota for that type of GPU; switch to T4 or CPU.
• To run a notebook: colab exec -s job -f nb.ipynb; results are written to nb_output.ipynb in the same directory.
• For high memory: --high-mem (requires Pro or Pro+).
• For SSH or IDE connection: colab ssh -s job.
• When running multiple jobs in parallel, use --config <path> to isolate session state.
• For troubleshooting: colab status -s job, colab log -s job -n 20. If a session was reclaimed, check with colab sessions and then recreate it.

Route 2: Colab Remote MCP

Setup

Endpoint: https://colaboratory.googleapis.com/mcp. Before use, you need to enable the MCP server in a Google Cloud project and complete authentication, following Google's official documentation (enable guide, authentication guide). When authenticating with the user's own identity, the MCP client has the same permissions as the user, and actions are recorded under the user's name.

Add this address as a remote MCP server in any client that supports remote MCP. For how to add a custom connector in a given client, follow that client's own documentation.

Tools

Tool	Purpose
get_subscription	Check whether the user is on Free, Pro, or Pro+
list_runtime_specs	List the machine types that can be requested (model, accelerator, specs) and whether the user is eligible
create_runtime	Start a runtime. It is rate-limited, so prefer reusing an existing one from list_runtimes
list_runtimes / get_runtime	View allocated runtimes
create_session / list_sessions / delete_session	Open, list, and close Jupyter sessions on the same machine, used to isolate state
execute_code	Execute Python; returns stdout, stderr, the value of the last expression, and errors
delete_runtime	Delete the runtime and permanently clear its state

Key Points

• To isolate state, call create_session on an existing runtime rather than starting another machine.
• execute_code returns text only; images and charts are not returned, so save them to files if you need them. Long output gets truncated.
• A single streaming output is capped at 600 seconds. For long tasks, pass a fixed executionId (UUID); if it times out, call again with the same ID to reattach to the result. Without an ID, the task keeps running after a timeout but cannot be reattached.
• Wrapping up: for small tasks, close the session with delete_session; when the whole job is finished, or you hit TOO_MANY_ACTIVE_RUNTIMES, run delete_runtime. If the user explicitly says they no longer need it, delete the runtime so it does not sit idle.

Choosing a Route

• Need to transfer files, mount Drive, use SSH, or run a full training or deployment script: CLI.
• User is in a mobile or web chat, the local machine is off, and they just want to start a machine, run a snippet, and shut it down: MCP.
• The two can be combined: a session started by the CLI can be taken over in the browser with colab url -s <name>.

Output Format

1. Which GPU was used, how long it ran, and whether the session or runtime has been released.
2. Key output from the code, and where result files were downloaded.
3. If there was a fallback (the desired GPU was not granted) or a failure, state the cause.
4. If any machine was not released (at the user's request), clearly remind them that it is still consuming compute units.