Connecting to Google Colab's Remote MCP Endpoint on Linux Without Re-Logging In
Contents
I tested Google Colab’s remote MCP endpoint (Model Context Protocol, a standard interface for AI agents to call external tools) from a local Linux machine.
Even without logging in or sending credentials, the server returned all 10 available tool names, but calling list_runtimes to inspect my own runtimes (Colab’s cloud compute environments for running Python) required authentication. Once I approved access on Google’s browser consent screen and saved the refresh token (a long-lived credential used to mint new access tokens), a separate Python process was able to obtain a fresh access token and query the runtime list without reopening the browser consent screen.
Connecting to Google’s MCP Without Opening a Notebook
Earlier in March, Google Colab released an open-source MCP server under the same name that runs locally on your machine and controls a Colab notebook open in your browser. The endpoint announced in November, https://colaboratory.googleapis.com/mcp, works differently: it lets you send HTTP requests directly to an MCP server hosted by Google without keeping a Colab notebook tab open. (Colab team’s November announcement / March announcement)
I first tried the March local server with Firefox. Starting the local server exposed a single browser-connection tool that waits up to 60 seconds for an open browser notebook to connect. Because no notebook connected, the tool call returned false after 60.19 seconds. (Timeout implementation in session.py)
To avoid relying on an open browser tab, I switched to the November remote endpoint and sent direct HTTP POST requests using Python’s standard library. In a standard MCP session, the client first sends initialize to negotiate the protocol version, follows with notifications/initialized, fetches the tool list via tools/list, and invokes a specific tool with tools/call. Sending those JSON-RPC requests in order without any authorization header or browser cookies produced the responses below. (Official MCP reference)
| Request Sent | HTTP | Response Returned |
|---|---|---|
initialize (session initialization) | 200 | Server name StatelessServer and protocol version 2025-03-26 |
notifications/initialized (init complete notice) | 202 | Empty body |
tools/list (available tool definitions) | 200 | 10 tools including list_runtimes and execute_code |
tools/call targeting list_runtimes | 401 | isError: true with a message saying credentials are required |
Calls up through tools/list only report which tools the server exposes, so they succeed with HTTP 200 before login. Once you call list_runtimes to inspect the runtimes assigned to your Google account, the server rejects the request with HTTP 401 (unauthorized) and a JSON error payload. You can reproduce that 401 response from a terminal using curl to send the same JSON-RPC request without writing Python. (list_runtimes reference)
curl -i 'https://colaboratory.googleapis.com/mcp' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
--data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_runtimes","arguments":{}}}'
Do You Have to Open a Browser Login Screen on Every Connection?
The 401 response also included an OAuth metadata URL for checking required permissions, which listed only a single required scope: https://www.googleapis.com/auth/colaboratory. (Auth metadata from the 401 response)
The official setup guide instructs you to enable the Colab API in a Google Cloud project and configure an OAuth client (app credentials registered with Google). With Google’s desktop app OAuth flow, the client opens a browser for one-time consent, catches the redirect on a temporary local HTTP listener, and receives two credentials: a short-lived access token for API calls and a refresh token. Saving that refresh token to disk lets later processes request new access tokens without reopening the browser. (Colab setup guide / Desktop app token refresh)
One catch is that in Google Cloud’s OAuth consent screen settings, if an external app’s publishing status is left in “Testing”, issued refresh tokens expire after 7 days. On my machine, I already had a desktop OAuth client whose publishing status is “In production” for reading Google Analytics, Search Console, and AdSense reports, so that 7-day limit does not apply to it. (Google OAuth expiration rules)
Because that existing client only had read-only scopes granted for those three services, I reused the same production client to approve Colab access once and saved the Colab refresh token to a separate file so it would not touch the existing token file.
Running on Linux, I started the local port listener to wait for Google’s redirect callback and opened the consent screen in Firefox. On the first try, the browser did not return an approval response within the listener’s 15-minute wait window, so the listener exited and no token was saved. When Firefox eventually redirected back to that local port afterward, the listener had already stopped and hit a connection error. Starting the auth flow over and clicking Allow in the newly opened tab sent the callback to the active listener on the same machine and saved the refresh token.
Calling list_runtimes with the access token obtained right after consent returned HTTP 200. When I then started a separate Python process, exchanged the saved refresh token for a fresh access token, and called list_runtimes again, it returned HTTP 200 with the runtime list without opening a browser consent screen. That said, I only tested reconnection within the same day and have not verified whether the token still works after more than 7 days.
Checking Plan Tier and Eligible GPUs Before Creating a Runtime
Once authentication succeeded, I checked the account’s subscription tier and eligible GPU types before actually launching a compute environment. Calling get_subscription returned Colab Pro, and list_runtime_specs showed T4, L4, A100, and G4 as eligible, while H100 was not eligible. Even when a GPU appears eligible in this list, launching one still fails if there is no accelerator capacity available at that moment. (Runtime selection and launch conditions)
Actually running code would be the next step after these checks: you create a runtime with create_runtime, open a stateful Python session inside it with create_session, run code with execute_code, and clean up with delete_runtime when finished (for this test, I stopped after checking the plan and eligible GPUs and did not create a runtime). (Colab MCP tool reference)