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 Colab runtime and waits until it's ready. Creation is slow and quota-limited, so reuse a runtime from `list_runtimes` when you can, and use a new session (`create_session`) rather than a new runtime to isolate state. Set `runtime.runtimeSpec` to a spec from `list_runtime_specs` that the user is eligible for. Pass a new UUID as `requestId` for each runtime you create. If the call fails with DEADLINE_EXCEEDED, the runtime is still being created, and repeating the identical call waits for it instead of creating another. FAILED_PRECONDITION means the user can't get this runtime now, for example because there's no capacity for the accelerator, their usage quota is used up, or they have too many active runtimes. Try another eligible spec, reuse a runtime, or retry later. On RESOURCE_EXHAUSTED (rate limit), nothing was created; retry with exponential backoff.
`create_session`	Opens a Jupyter kernel session on a runtime (`runtimes/{runtime_id}`) and returns its name (`runtimes/{runtime_id}/sessions/{session_id}`). `execute_code` calls that target the session share its kernel state (variables, imports). Reuse a session you opened rather than opening another, and close it with `delete_session` when you're done, because each open session holds kernel memory. Opening a session with the ID of an open one returns that session.
`delete_session`	Closes a session (`runtimes/{runtime_id}/sessions/{session_id}`), discarding its kernel state and aborting any `execute_code` call running in it. Files it wrote stay on the runtime, and the runtime keeps running.
`execute_code`	Runs Python in a Colab runtime's Jupyter kernel. Returns stdout, stderr, the value of the last expression (`result`), and any exception (`executionError`). Only text is returned, not images or plots. Output over the size limit is truncated and flagged with `outputTruncated`. Set exactly one target: `session` (`runtimes/{runtime_id}/sessions/{session_id}`) runs in that session's kernel, sharing variables and imports with its other calls. The session is created if it doesn't exist. Use this for anything stateful or multi-step. `runtime` (`runtimes/{runtime_id}`) runs in a new session, which stays open. The result's `session` names it: reuse it, or close it with `delete_session`. Calls to one session run one at a time, so parallel calls to it only queue and can time out. For parallel work, use a session per task and close each when it's done. For code that may run long, pass a new UUID as `executionId` with a `session` target. A call is cut off after 600s with DEADLINE_EXCEEDED, but the code keeps running. After that, or if the call fails with UNAVAILABLE, repeat the identical call (same `session` and `executionId`). It reattaches and returns the output and result if the code had started, and otherwise runs it. Prefer this to running code in the background and polling it. Use a new UUID for each new execution, because once the result has been returned the same `executionId` runs the code again. Without an `executionId`, or with a `runtime` target, a timed-out execution can't be reattached, and a retry may run the code twice. Cancelling a call (`notifications/cancelled`) interrupts whatever the session's kernel is running, which may be another call's code. NOT_FOUND means the runtime doesn't exist, or has stopped. Find one with `list_runtimes`, and create one only if there's none. RESOURCE_EXHAUSTED (rate limit) means the code didn't run; retry with exponential backoff. To move files between your machine and the runtime, use HTTP as described in `get_runtime`, not base64 through this tool, because the bytes fill your context. Files persist on the runtime across sessions.
`get_subscription`	Gets the user's Colab subscription tier: free, Pro or Pro+. https://colab.research.google.com/signup compares the tiers.
`list_sessions`	Lists the open sessions on a runtime (`runtimes/{runtime_id}`), including ones you didn't open, such as the user's notebooks. Use it to find a session of yours to reuse or close. Close only sessions you opened. It returns names only, not what is running in them.
`delete_runtime`	Deletes a runtime (`runtimes/{runtime_id}`) and everything on it: files, sessions and their state. This can't be undone. Delete a runtime only when the user asks, or to free up one you created when `create_runtime` fails because the user has too many active runtimes. To reset or isolate state, close a session with `delete_session` instead.
`get_runtime`	Gets a runtime (`runtimes/{runtime_id}`), including its spec and `connectionInfo`. 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 without the leading slash, 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 the user's Colab runtimes, with their specs and `connectionInfo`. Check here for a runtime to reuse before calling `create_runtime`.
`list_runtime_specs`	Lists the runtime specs (variant, accelerator and shape) and whether the user is eligible for each. Call it before `create_runtime` to pick a spec.

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
}'