MCP Reference: colaboratory.googleapis.com

Provides tools to manage Colab runtimes and execute code in them.

A Model Context Protocol (MCP) server acts as a proxy between an external service that provides context, data, or capabilities to a Large Language Model (LLM) or AI application. MCP servers connect AI applications to external systems such as databases and web services, translating their responses into a format that the AI application can understand.

Server Setup

You must enable MCP servers and set up authentication before use. For more information about using Google and Google Cloud remote MCP servers, see Google Cloud MCP servers overview.

Server Endpoints

An MCP service endpoint is the network address and communication interface (usually a URL) of the MCP server that an AI application (the Host for the MCP client) uses to establish a secure, standardized connection. It is the point of contact for the LLM to request context, call a tool, or access a resource.

The Colab API MCP server has the following global MCP endpoint:

https://colaboratory.googleapis.com/mcp

MCP Tools

An MCP tool is a function or executable capability that an MCP server exposes to a LLM or AI application to perform an action in the real world.

Tools

The colaboratory.googleapis.com MCP server has the following tools:

MCP Tools
`create_runtime`	Creates a new Colab runtime assignment for the requesting user. Use `list_runtime_specs` to discover eligible machine configurations that can be requested when creating a new runtime. Several requests-per-minute quotas are enforced on this tool call, so prefer to reuse an existing runtime from `list_runtimes` if possible. For state isolation, open a new Jupyter session using `create_session` on an existing runtime instead of creating one.
`create_session`	Opens a Jupyter kernel session on a Colab runtime, identified by its resource name (`runtimes/{runtime_id}`). Sessions group subsequent `execute_code` calls so they share kernel state (variables, imports, etc.). An optional `session_id` may be supplied. If omitted, the server generates a random UUID. If supplied, `session_id` must be 1-63 characters, contain only lowercase ASCII letters, digits, and hyphens, start with a letter, and end with a letter or digit (RFC 1034). Returns the new session as `runtimes/{runtime_id}/sessions/{session_id}`. The session lives until the runtime is deleted or the session is closed via `delete_session`. Abandoned sessions hold kernel memory. Reuse a session you opened instead of opening a new one. Rate limited. If a call fails with a rate limit error (RESOURCE_EXHAUSTED), it did not run. Retry with exponential backoff.
`delete_session`	Closes an open Jupyter kernel session on a Colab runtime, identified by its resource name (`runtimes/{runtime_id}/sessions/{session_id}`). The session's in-kernel Python state (variables, imports, etc.) is discarded. Files written by the session persist on the runtime's filesystem. The parent runtime itself is not removed. Any in-flight `execute_code` calls targeting this session are aborted. Rate limited. If a call fails with a rate limit error (RESOURCE_EXHAUSTED), it did not run. Retry with exponential backoff.
`execute_code`	Executes Python in a Colab runtime's Jupyter kernel and returns the captured stdout, stderr, the last expression's value, and any error. Target exactly one of `runtime` (`runtimes/{runtime_id}`), which runs in a fresh kernel session, or `session` (`runtimes/{runtime_id}/sessions/{session_id}`), which runs in that session and shares kernel state (variables, imports, loaded data) with its other calls. A session is created if it does not already exist. Each call that targets a `runtime` opens a new session and leaves it open, so repeated calls pile up kernels and use the runtime's memory. The result's `session` names it: close it with `delete_session` when you are done (`list_sessions` finds strays, but it also lists sessions you did not open, such as a user's notebooks: close only your own). To run several snippets, open one session with `create_session` (or reuse the `session` from the first result), target it with `session`, and run the calls one after another. Close it when you are done. Calls to one session run one at a time on its kernel, so issuing them in parallel only queues them, and queued calls can time out. For parallel work, use a separate session for each call, and close each with `delete_session` when it is done. stdout and stderr stream incrementally as progress notifications and are also returned aggregated in the result. To make an execution resumable, pass a stable `executionId` (a UUID) and target a `session` (not a `runtime`). A call that outlives the streaming deadline (600s) ends with a DEADLINE_EXCEEDED error before returning a result. To recover, re-issue the identical call (same `session` and `executionId`) to reattach and keep streaming through to the final result. A `runtime` target opens a fresh session on every call, so it cannot reattach to an earlier execution: target a `session` from the start whenever you may need to resume. Reattaching works only until the result is returned. Reusing the same `executionId` after that starts a new execution, so use a new UUID for each distinct execution. Without an `executionId`, an execution that outlives the deadline keeps running but cannot be reconnected to. Clients use the standard MCP `notifications/cancelled` flow on an in-flight execution. When cancelled, interrupts the session's kernel, which stops whatever the kernel is running, possibly another call's code, and may also abort calls queued behind it. Cancelling a reattached call interrupts the original execution too. If a call fails with NOT_FOUND, the runtime doesn't exist, isn't assigned to you, or no longer answers at its address: check `list_runtimes` for one that is, and only if there is none create one with `create_runtime`. If it fails with UNAVAILABLE or DEADLINE_EXCEEDED, the runtime may be slow or unreachable, or the connection may have dropped while the code ran, so the code may still be running. If you targeted a `session` and passed an `executionId`, reattach with the same `session` and `executionId` instead of starting a new execution, and back off between retries. If you targeted a `runtime` or passed no `executionId`, a retry runs the code again if it had started. `list_sessions` only names open sessions and says nothing about what is running or has finished, so use it to find and close a session that a `runtime` call opened, and check the kernel's state or the files the code writes before re-running code that isn't safe to repeat. Only text is returned. Rich outputs (images, plots, widgets) are not returned. Oversized output is truncated and flagged via `outputTruncated`. Files written to disk persist on the runtime regardless of session. Don't transfer files between your machine and the runtime by base64-encoding them through this tool, because the bytes fill your context. Use HTTP directly with the `connectionInfo` from `get_runtime` instead. Rate limited. If a call fails with a rate limit error (RESOURCE_EXHAUSTED), it did not run. Retry with exponential backoff.
`get_subscription`	Gets the subscription of the requesting user. Use it when you need to know if the user subscription tier is free, pro or pro+. https://colab.research.google.com/signup shows the differences between tiers.
`list_sessions`	Lists the open Jupyter kernel sessions on a Colab runtime, identified by its resource name (`runtimes/{runtime_id}`). Returns every session currently open on the runtime, including sessions opened outside of MCP (for example by a browser pointing at the same runtime). The runtime is bound to the requesting user, so all returned sessions belong to the caller. Use this to find sessions you opened to reuse with `execute_code`, or to find sessions to close with `delete_session`. Rate limited. If a call fails with a rate limit error (RESOURCE_EXHAUSTED), it did not run. Retry with exponential backoff.
`delete_runtime`	Unassigns and deletes a Colab runtime owned by the requesting user, identified by its resource name (`runtimes/{runtime_id}`), and returns an empty response on success. The runtime and its associated state are permanently removed. To preserve runtime state in an agentic session, this should only be called if a user reaches the `TOO_MANY_ACTIVE_RUNTIMES` limit or explicitly requests deletion. For small, independent units of work within the same agentic session, prefer using `delete_session` to close Jupyter sessions instead of deleting the entire runtime.
`get_runtime`	Retrieves a single Colab runtime assigned to the requesting user by its resource name (`runtimes/{runtime_id}`), including its specification and the connection info needed to connect to it. To transfer files without passing their bytes through tool calls, send HTTP requests to `connectionInfo.url` with the header `X-Colab-Runtime-Proxy-Token: {connectionInfo.token}`. Paths are absolute with the leading slash dropped, e.g. `content/data.csv` for `/content/data.csv`. Download: `GET {url}/files/{path}` returns raw bytes and supports `Range`. Upload: `PUT {url}/api/contents/{path}` with JSON `{"type":"file","format":"base64","content":"..."}`, or `"format":"text"` for text. The parent directory must exist; create it with `{"type":"directory"}`, one level per request. Keep each request under 50 MB of file data. For larger files, send pieces to the same path with `"chunk": 1`, `2`, and so on, and `"chunk": -1` on the last piece. The token expires at `connectionInfo.expireTime`, about an hour after it's issued; call this tool again for a new one. A missing or expired token returns 404.
`list_runtimes`	Lists all Colab runtimes currently assigned to the requesting user. Each returned runtime includes its specification and the connection info needed to connect to it.
`list_runtime_specs`	Lists the Colab runtime specifications (combinations of variant, accelerator, and shape) that are available to the requesting user, along with whether the user is eligible for each. Use this to discover which machine configurations can be requested when creating a runtime.

Get MCP tool specifications

To get the MCP tool specifications for all tools in an MCP server, use the tools/list method. The following example demonstrates how to use curl to list all tools and their specifications currently available within the MCP server.

Curl Request
curl --location 'https://colaboratory.googleapis.com/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/list", "jsonrpc": "2.0", "id": 1 }'

Curl Request

curl --location 'https://colaboratory.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'