Google Colab Provider

The Jupyter MCP Server can execute code against a Google Colab code sandbox. Colab exposes a Jupyter-compatible kernel behind an authenticating proxy, so the server connects to it through the code-sandboxes colab sandbox variant.

tip

For the full, engine-level credential and parameter reference, see the Colab sandbox guide in the code-sandboxes documentation.

Requirements

Install the Colab extra:

pip install "jupyter-mcp-server[colab]"

Install the sandbox extension package used by this provider:

pip install datalayer_mcp_sandboxes

Connection parameters

You obtain the following values from an active Colab browser session:

Parameter	Environment variable	Description
Server URL	CODE_SANDBOX_URL	The Colab tunnel URL for the code sandbox
Kernel ID	CODE_SANDBOX_ID	The assigned kernel identifier
Proxy token	CODE_SANDBOX_PROXY_TOKEN	The colab-code-sandbox-proxy-token value

How to obtain these values

The three values are the pieces of the WebSocket URL that Colab's own frontend uses to reach your assigned code sandbox:

wss://<host>/api/kernels/<kernel_id>/channels?session_id=<...>&colab-code-sandbox-proxy-token=<proxy_token>&colab-client-agent=web

Read them from your browser's developer tools:

1. Open your notebook on colab.research.google.com and connect to a code sandbox (Runtime → Connect, or run any cell).
2. Open DevTools (F12) → Network tab, select the WS filter (or type kernels), then run a cell to trigger kernel traffic.
3. Click the .../api/kernels/<kernel_id>/channels?... request and read off:
   • CODE_SANDBOX_URL — scheme + host before /api/kernels (change wss:// to https://). Colab assigns a per-session host such as https://8080-m-s-kkb-...-d.us-east1-0.prod.colab.dev; there is usually no /tun/m/... path segment.
   • CODE_SANDBOX_ID — the UUID after /api/kernels/.
   • CODE_SANDBOX_PROXY_TOKEN — the colab-code-sandbox-proxy-token query parameter (same value as the X-Colab-Runtime-Proxy-Token header). Ignore the session_id and colab-client-agent parameters.

Consumer Colab does not expose an official third-party API to provision code sandboxes from scratch. Start/connect a code sandbox in the Colab UI first, then reuse it here.

Configuration

Select the Colab engine with SANDBOX_VARIANT=colab:

SANDBOX_VARIANT=colab
CODE_SANDBOX_URL=https://8080-m-s-kkb-...-d.us-east1-0.prod.colab.dev
CODE_SANDBOX_ID=c9bba548-3995-4f26-8e1a-7b8fbb10c578
CODE_SANDBOX_PROXY_TOKEN=eyJhbGci....

Or via the command line:

jupyter mcp start \
  --transport streamable-http \
  --sandbox-variant colab \
  --code-sandbox-url "https://8080-m-s-kkb-...-d.us-east1-0.prod.colab.dev" \
  --code-sandbox-id "c9bba548-3995-4f26-8e1a-7b8fbb10c578" \
  --code-sandbox-proxy-token "eyJhbGci...." \
  --port 4040

Once connected, all notebook and cell execution tools run against the Colab code sandbox transparently.

note

The proxy token is short-lived. Refresh it from the active Colab session when it expires.

Optional: configure from channels URL

Instead of setting CODE_SANDBOX_URL and CODE_SANDBOX_ID separately, you can provide the full WebSocket channels URL:

SANDBOX_VARIANT=colab
CODE_SANDBOX_CHANNELS_URL="wss://<host>/api/kernels/<kernel_id>/channels?session_id=<...>&colab-code-sandbox-proxy-token=<proxy_token>&colab-client-agent=web"
CODE_SANDBOX_PROXY_TOKEN=<proxy_token>

Or on the command line:

jupyter mcp start \
  --transport streamable-http \
  --sandbox-variant colab \
  --code-sandbox-channels-url "wss://<host>/api/kernels/<kernel_id>/channels?..." \
  --code-sandbox-proxy-token "<proxy_token>" \
  --port 4040