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

A [Model Context Protocol (MCP) server](https://modelcontextprotocol.io/docs/learn/server-concepts) 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](https://docs.cloud.google.com/mcp/enable-disable-mcp-servers) and [set up authentication](https://docs.cloud.google.com/mcp/authenticate-mcp) before use. For more information about using Google and Google Cloud remote MCP servers, see [Google Cloud MCP servers overview](https://docs.cloud.google.com/mcp/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](https://modelcontextprotocol.io/legacy/concepts/tools) 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. 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). 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 with the same `executionId` to reattach and keep streaming through to the final result. Reattaching works only until the result is returned. Reusing the same `executionId` after that starts a new 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 kernel. 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. A kernel runs one cell at a time, so parallel calls on one session queue and can time out. Each call that targets a `runtime` opens a new session that stays open until `delete_session` closes it, so parallel calls can exhaust the runtime's memory. For several calls, pass the same `session` each time (or the session returned in the first result) and run them one after another. Reattaching with an `executionId` works only when the call targets a `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 |
|---|
| ```bash 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 }' ``` |