Colab MCP exposes MCP tools to the connected AI agent through two categories: tools that are always present from the moment the server starts, and tools that are injected dynamically once a live Google Colab browser session establishes its WebSocket connection. The always-present tool handles connection bootstrapping, while the dynamic tools represent the full capabilities of the Colab notebook environment and vary depending on what the Colab session itself exposes.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/googlecolab/colab-mcp/llms.txt
Use this file to discover all available pages before exploring further.
Always-Present Tools
open_colab_browser_connection
This tool is injected via ToolInjectionMiddleware at startup and is always available to the AI agent, regardless of whether a Colab session is currently connected. Its primary purpose is to initiate and confirm a live browser-side connection to Google Colab before any notebook operations are attempted.
Description (from source): “Opens a connection to a Google Colab browser session and unlocks notebook editing tools. Returns a boolean representing whether the connection attempt succeeded”
Behavior
The tool follows a different code path depending on whether a Colab session is already live:- If already connected — returns
trueimmediately without opening any browser window or waiting. - If not connected — calls
webbrowser.open_new()to open the following URL in the user’s default browser:
mcpProxyToken and mcpProxyPort fragment parameters allow the Colab tab to authenticate against the local ColabWebSocketServer.
After opening the browser, ColabProxyMiddleware.on_call_tool intercepts the result and waits up to 60 seconds (UI_CONNECTION_TIMEOUT = 60.0) for the Colab tab to connect. During this wait, it reports progress back to the MCP client in three steps:
| Step | Progress | Message |
|---|---|---|
| 1 | 1/3 | ”The user is not connected to the Colab UI” |
| 2 | 2/3 | ”Waiting for user to connect in Colab - will wait for 60s” |
| 3 | 3/3 | ”The Colab UI is successfully connected!” or “Timeout while waiting for the user to connect.” |
Return Value
true if the Colab browser session connected successfully within the timeout window; false if the 60-second wait elapsed without a connection being established.Example Response
Dynamic Notebook Tools
Once a Colab browser session connects to the local WebSocket server, Colab MCP usesFastMCPProxy to proxy the tools exposed by the Colab UI directly to the MCP client. These tools are not defined in the Colab MCP server itself — they are forwarded transparently from whatever tools the connected Colab session makes available.
Dynamic notebook tools:
- Are not available until
open_colab_browser_connectionsucceeds. - Appear in the MCP client’s tool list only after the session connects.
- Are surfaced to the MCP client via a
notifications/tools/list_changednotification sent byColabProxyMiddlewarewhen it detects the connection state has changed. - Are served through
ColabProxyClient.client_factory(), which returns the live proxy client when connected or a stubbed empty client when disconnected.
Notebook tools disappear from the MCP client’s tool list when the Colab browser tab disconnects. When this happens,
ColabProxyMiddleware detects the state change on the next incoming MCP message and sends a notifications/tools/list_changed notification, prompting the MCP client to refresh its tool list.