Skip to main content

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.

Colab MCP uses two FastMCP middleware layers to manage the Colab browser connection and surface the open_colab_browser_connection tool. The first — ColabProxyMiddleware — intercepts every MCP message to track connection state, populate per-request context, and handle the special connection-wait logic for open_colab_browser_connection. The second — ToolInjectionMiddleware — is a standard FastMCP component that injects the open_colab_browser_connection tool into the server’s tool list. Together they ensure the AI agent always has access to the bootstrapping tool and that the MCP client is kept informed as the Colab session connects and disconnects.

​
ColabProxyMiddleware

Module: colab_mcp.session
Base class: fastmcp.server.middleware.Middleware ColabProxyMiddleware sits at the outermost position in the middleware chain. It wraps every MCP message exchange to propagate connection metadata into the request context and to detect connectivity changes that must be signalled to the MCP client.

​
on_message(context, call_next)

async def on_message(context: MiddlewareContext, call_next) -> Any
Called for every incoming MCP message. Before forwarding the message down the chain, it writes three state values into the FastMCP request context:
State keyTypeDescription
fe_connectedboolWhether the Colab browser session is currently connected (ColabProxyClient.is_connected())
proxy_tokenstrThe authentication token of the ColabWebSocketServer
proxy_portintThe port the ColabWebSocketServer is listening on
After call_next(context) returns, the middleware checks whether the connection state has changed since the previous message (comparing the current is_connected() result against self.last_message_connected). If the state changed, it calls context.fastmcp_context.send_tool_list_changed() to notify the MCP client that the available tool list has been updated.

​
on_call_tool(context, call_next)

async def on_call_tool(context, call_next) -> ToolResult
Called whenever the MCP client invokes a tool. For most tools this method simply returns the result of call_next(context) unchanged. For the open_colab_browser_connection tool, the method always calls call_next(context) first (which triggers check_session_proxy_tool_fn to open the browser if needed). After call_next returns, if is_connected() is True, the raw result is returned immediately — no waiting occurs. If is_connected() is False after call_next returns, the method takes over the response and performs the connection wait:
  1. Reports progress step 1/3: "The user is not connected to the Colab UI".
  2. Reports progress step 2/3: "Waiting for user to connect in Colab - will wait for 60s".
  3. Calls await proxy_client.await_proxy_connection() — waits up to UI_CONNECTION_TIMEOUT (60.0s).
  4. Reports progress step 3/3:
    • On success: "The Colab UI is successfully connected!" — returns ToolResult with {"result": True}.
    • On timeout: "Timeout while waiting for the user to connect." — returns ToolResult with {"result": False}.
This synthesized ToolResult is returned instead of the raw result from call_next, so the MCP client always receives a clear boolean outcome.

​
open_colab_browser_connection Tool (Injected)

The open_colab_browser_connection tool is defined in colab_mcp.session via Tool.from_function and is injected into the server’s tool list by ToolInjectionMiddleware. It is the function that actually opens the browser and reads connection state from the FastMCP context.

​
Tool definition

check_session_proxy_tool = Tool.from_function(
    fn=check_session_proxy_tool_fn,
    name="open_colab_browser_connection",
    description="Opens a connection to a Google Colab browser session and unlocks notebook editing tools. Returns a boolean representing whether the connection attempt succeeded",
)

​
Function: check_session_proxy_tool_fn

async def check_session_proxy_tool_fn(ctx: Context = CurrentContext()) -> bool
The underlying function executed when the tool is called. It reads the three state keys set by ColabProxyMiddleware.on_message from the FastMCP Context:
State key readUsed for
fe_connectedDetermine whether a Colab session is already active
proxy_tokenBuild the Colab URL fragment
proxy_portBuild the Colab URL fragment
If fe_connected is True: Returns True immediately. No browser is opened. If fe_connected is False: Calls webbrowser.open_new() with the following URL: 
https://colab.research.google.com/notebooks/empty.ipynb#mcpProxyToken=<token>&mcpProxyPort=<port>
Then returns False. The actual connection wait is handled upstream by ColabProxyMiddleware.on_call_tool, which intercepts this False result and awaits the full connection before returning the final ToolResult to the MCP client.
ToolInjectionMiddleware is provided by fastmcp.server.middleware.tool_injection and is a standard FastMCP component. Colab MCP does not implement it — it simply instantiates it with tools=[check_session_proxy_tool] and appends it to the middleware list.

Build docs developers (and LLMs) love

Get started for freeTalk to us