Google Colab Remote MCP Server
Google's official hosted Colab Remote MCP Server (https://colaboratory.googleapis.com/mcp, introduced November 17, 2026 alongside the v1beta Colab REST API) lets MCP-compatible agents provision cloud CPU, GPU, and TPU runtimes and execute Python headlessly over Streamable HTTP with OAuth scope https://www.googleapis.com/auth/colaboratory—without an open browser tab or local uvx bridge. Google AI Ultra grants 1,000 compute units (CU)/month on Ultra 5x (from $99.99/mo) and 2,000 CU/month on Ultra 20x ($199.99/mo); reaching 2,500 CU/month requires stacking Ultra 20x with a standalone Colab Pro+ subscription (500 CU/month, $49.99/mo) on the same Google Account, rather than coming from Ultra alone.
1. Official remote endpoint & 10 MCP tools
Unlike the earlier March 2026 open-source local bridge (googlecolab/colab-mcp, listed separately at Colab MCP), the hosted remote server at https://colaboratory.googleapis.com/mcp accepts standard JSON-RPC 2.0 requests (Content-Type: application/json, Accept: application/json, text/event-stream). Unauthenticated tools/list discovery exposes 10 tools, while tools/call returns 401 Unauthorized with WWW-Authenticate: Bearer resource_metadata="https://colaboratory.googleapis.com/.well-known/oauth-protected-resource/get_subscription":
| Tool | Role & Behavior | Required Args | Key Constraints & Annotations |
|---|---|---|---|
list_runtime_specs | Lists eligible CPU, GPU (T4, L4, A100), and TPU specs | — | Read-only, idempotent (VARIANT_CPU, VARIANT_GPU, VARIANT_TPU; SHAPE_STANDARD / SHAPE_HIGHMEM) |
list_runtimes | Lists active Colab runtimes with specs & connectionInfo | — | Read-only; check here to reuse runtimes before creating new ones |
get_runtime | Fetches spec and proxy connectionInfo for runtimes/{id} | name | Read-only; proxy token expires in ~1 hour (connectionInfo.expireTime) |
create_runtime | Provisions a runtime and waits until ready | runtime | Slow & quota-limited; pass new UUID4 requestId for idempotency |
delete_runtime | Permanently deletes a runtime, files, and sessions | name | Destructive, idempotent; irreversible cleanup |
list_sessions | Lists open Jupyter kernel sessions on a runtime | parent | Read-only; returns session names only (includes user notebook sessions) |
create_session | Opens a stateful Jupyter kernel session on a runtime | parent | Non-idempotent unless reusing an existing session ID |
delete_session | Closes a session and aborts active execute_code runs | name | Destructive; keeps files on the runtime VM |
execute_code | Runs Python in a session or new runtime session | code | Destructive, open-world; text output only, 600s cutoff (executionId reattach) |
get_subscription | Returns tier (FREE, PRO, or PRO_PLUS) | — | Read-only, idempotent |
File transfer & long-running execution rules
- Do not pass files through
execute_codeas base64: Official tool docs warn that bytes inside tool calls fill context. Instead, callget_runtimeforconnectionInfo.urland sendX-Colab-Runtime-Proxy-Token: {connectionInfo.token}(404on missing/expired token). - Direct HTTP file I/O: Download with
GET {url}/files/{path}(raw bytes, supports HTTPRange; paths omit the leading slash, e.g.content/output.mp4). Upload withPUT {url}/api/contents/{path}using JSON{"type":"file","format":"base64"|"text","content":"..."}under 50 MB per request, or chunk larger files with"chunk": 1, 2, ..., -1(parent directories must exist via{"type":"directory"}). - 600-second cutoff & reattach:
execute_codecalls time out at 600s (DEADLINE_EXCEEDED) while Python execution continues on the kernel. Pass a fresh UUID4executionIdalongside asessiontarget; repeating the exact samesession+executionIdreattaches and fetches output without re-running completed work.
2. Google AI Ultra & Colab Compute Unit (CU) rules
Public confusion around "Ultra 2,500 CU" usually mixes up Google AI Ultra's native Colab compute unit grant, Colab Pro+ stacking, and Google One's separate AI Credits system. The official tables from Google One and Colab break down as follows:
| Plan / Option | Monthly Price (USD) | Colab Compute Units | Key Runtime & Quota Rules |
|---|---|---|---|
| Colab Free | $0 | 0 (dynamic free pool) | Up to 12h runtime; non-guaranteed GPUs; strict UI-bypass termination |
| Google AI Plus | $4.99/mo (varies by tier) | 50 CU/month | Expanded accelerators vs Free; unused CUs expire after 90 days |
| Colab Pro | $9.99/mo | 100 CU/month | Faster GPUs, high-memory shapes; unused CUs expire after 90 days |
| Google AI Pro | $19.99/mo | 200 CU/month | Bundled Google One + Colab CUs + $10/mo Cloud credits (GDP) |
| Colab Pro+ | $49.99/mo | 500 CU/month | Priority GPUs & up to 24h background execution |
| Google AI Ultra (5x) | From $99.99/mo | 1,000 CU/month | Uninterrupted 24h background execution, Premium GPUs, $40/mo Cloud credits |
| Google AI Ultra (20x) | $199.99/mo | 2,000 CU/month | Highest Ultra CU tier, 24h background execution, $100/mo Cloud credits |
| Ultra 20x + Colab Pro+ (Stacked) | $199.99 + $49.99/mo | 2,500 CU/month | Official FAQ confirms Google AI plan + Colab Pro+ balances stack |
| Pay As You Go | $9.99 / $49.99 one-time | 100 / 500 CU | No recurring subscription; unused CUs expire after 90 days |
Four rules that affect automated MCP jobs
- 2,500 CU comes from stacking—or confusion with AI Credits: Google AI Ultra natively grants 1,000 CU/mo (5x) or 2,000 CU/mo (20x). Combining Ultra 20x (2,000 CU) with standalone Colab Pro+ (500 CU) on the same Google Account legally pools 2,500 CU/month (arriving on separate monthly deposit dates). Separately, Google One sells 2,500 / 5,000 / 20,000 AI Credits for Flow, Antigravity, and Gemini overages—those credits do not buy Colab GPU time.
- 90-day expiry & no family sharing: Unused compute units expire 90 days after grant or purchase. Per Google One and Colab terms, bundled Colab CUs belong exclusively to the Google One plan manager and cannot be shared across family group members.
- Free-trial exclusion: Google AI plan Colab benefits are excluded during promotional or extended Google One free trials and only activate in countries where paid Colab plans are supported.
- CU exhaustion & anti-abuse limits: Exhausting your CU balance drops the account back to Free-tier restrictions and can terminate active backends. Managed runtimes also prohibit file hosting, media serving, or public web services unrelated to interactive compute.
3. Setup for Google Antigravity, Gemini CLI & OAuth clients
Live discovery at https://colaboratory.googleapis.com/.well-known/oauth-protected-resource/mcp specifies authorization_servers: ["https://accounts.google.com/"], while accounts.google.com/.well-known/openid-configuration exposes PKCE (S256) without Dynamic Client Registration (registration_endpoint) or Client ID Metadata Documents (client_id_metadata_document_supported). Therefore, generic OAuth clients cannot auto-register—use Google Application Default Credentials (ADC) or an explicit Google Cloud OAuth 2.0 Client ID.
Step 1: Enable the Colab API & authenticate ADC
gcloud config set project YOUR_PROJECT_ID
gcloud services enable colaboratory.googleapis.com
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/colaboratory,https://www.googleapis.com/auth/cloud-platform
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
Step 2: Configure Antigravity / T3 Code (mcp_config.json)
In standalone Antigravity (~/.gemini/config/mcp_config.json) or T3 Code's isolated Antigravity config (<t3-userdata>/providers/antigravity/<profile>/config/mcp_config.json, or <workspace>/.agents/mcp_config.json), use Streamable HTTP (serverUrl or url) with authProviderType: "google_credentials" and raise timeoutSeconds above the default 180s to match Colab's 600s execute_code cutoff:
{
"mcpServers": {
"google-colab": {
"serverUrl": "https://colaboratory.googleapis.com/mcp",
"authProviderType": "google_credentials",
"timeoutSeconds": 600
}
}
}
If you connect from a non-ADC OAuth client, create a Desktop/Web OAuth 2.0 client in the same Google Cloud project where colaboratory.googleapis.com is enabled, register the client's callback URL (for Antigravity: https://antigravity.google/oauth-callback), and supply oauth: { "clientId": "...", "clientSecret": "..." }. Note that Antigravity's legacy httpUrl key is deprecated in favor of serverUrl or url.
Remote MCP vs. local googlecolab/colab-mcp
| Dimension | Official Remote MCP (colaboratory.googleapis.com/mcp) | Local Bridge (googlecolab/colab-mcp via uvx) |
|---|---|---|
| Launch date | November 17, 2026 | March 17, 2026 |
| Transport | Hosted Streamable HTTP | Local stdio spawning browser-linked bridge |
| Browser required? | No (fully headless via Google Cloud OAuth/ADC) | Yes (bridges to an active Colab session) |
| Runtime provisioning | Built-in (list_runtime_specs, create_runtime, execute_code) | Controls notebook cells & active session |
| Best fit | Headless GPU batch runs, CI/agent pipelines, long executionId jobs | Interactive .ipynb cell editing alongside browser UI |
4. Operational limits & error handling
- Quota & creation retries:
create_runtimeis slow and enforces per-project and per-user RPM quotas (Quotas & System Limitsforcolaboratory.googleapis.com; per-user RPM cannot be raised). Always pass a fresh UUID4requestId; ifDEADLINE_EXCEEDEDreturns, repeat the identical call to wait for the in-flight VM rather than spawning duplicates.FAILED_PRECONDITIONsignals missing accelerator capacity, depleted CU quota, or too many active runtimes. - Sequential execution per session: Calls to the same
runtimes/{id}/sessions/{session_id}execute serially. For parallel GPU/CPU workers, open distinct sessions viacreate_sessionand clean up withdelete_sessionso idle kernels do not exhaust VM RAM. - Text-only tool return:
execute_codeomits inline plots and binary images. Save rendered images or video frames to/content/...and pull bytes viaGET {connectionInfo.url}/files/content/...withX-Colab-Runtime-Proxy-Token, refreshingget_runtimebefore the ~1-hourexpireTime.
Frequently asked questions
Does Google AI Ultra include 2,500 Colab compute units per month by itself?
No. According to Google One's official Google AI Plans table, Google AI Ultra 5x includes 1,000 Colab compute units/month and Google AI Ultra 20x includes 2,000 compute units/month. You only reach 2,500 CU/month by stacking Google AI Ultra 20x (2,000 CU) with a standalone Colab Pro+ subscription (500 CU/month) on the same Google Account, or when confusing Colab Compute Units with Google One's 2,500 AI Credits top-up pack.
How is https://colaboratory.googleapis.com/mcp different from googlecolab/colab-mcp?
googlecolab/colab-mcp (released March 2026) is an open-source local stdio MCP server launched with uvx that bridges your local agent to an interactive browser Colab session. The November 17, 2026 Google Colab Remote MCP server at https://colaboratory.googleapis.com/mcp is Google's hosted Streamable HTTP endpoint backed by the Colab v1beta REST API, allowing fully headless runtime creation, session control, and Python execution without a browser tab.
Can I use Google Colab Remote MCP with a Free Colab account or a Google One free trial?
The MCP endpoint accepts Free, Pro, and Pro+ tiers (discoverable via get_subscription), subject to API enablement and RPM quotas. However, Google AI plan Colab compute units are explicitly excluded during promotional or extended Google One free trials, and Free-tier runtimes remain subject to dynamic availability and stricter termination rules.
How should agents upload or download large media files on Colab Remote MCP?
Do not pass base64 file payloads through execute_code. Call get_runtime to obtain connectionInfo.url and a ~1-hour connectionInfo.token, then send HTTP requests with header X-Colab-Runtime-Proxy-Token: GET {url}/files/{path} for downloads (supports Range) and PUT {url}/api/contents/{path} in <50 MB chunks (using chunk: 1, 2, ..., -1) for uploads.
Primary sources
- Google Developers: Colab MCP Reference (colaboratory.googleapis.com)
- Google Developers: Colab REST API v1beta Reference
- Google Colab Medium: The Google Colab API and MCP Endpoint for Developers and Agents
- Google One: Official Google AI Plans & Colab Compute Units Table
- Google Colab FAQ: Compute Units, Stacking, Expiration & Usage Policies
- Google Developers Blog: Colab is now part of your Google AI plan
- Google Cloud Docs: Enable Supported MCP Servers
- Google Antigravity Docs: MCP Authentication & Server Configuration