research: Colab API MCP adapter spike (auth, cross-visibility, resumable execute_code) #7

Open
opened 2026-11-11 20:18:54 +00:00 by dsh · 1 comment
Owner

Google now ships a Colab API MCP server: https://colaboratory.googleapis.com/mcp (v1beta). Tools: list_runtime_specs, create_runtime, get_runtime, list_runtimes, delete_runtime, create_session, list_sessions, delete_session, execute_code, get_subscription. Reference: https://developers.google.com/colab/api/reference/mcp

Why it might be better than CLI shelling

  • structured runtime/session lifecycle; get_subscription gives the plan tier
  • execute_code streams stdout/stderr and is resumable via executionId (600 s stream deadline, reattach)
  • no CLI text parsing

Why it is not enough (yet)

  • no file upload/download, no Drive mount, no SSH — only text results; files stay on the VM
  • separate Google Cloud MCP OAuth setup; v1beta; create_runtime is rate-limited
  • sessions hold kernel memory; abandoned sessions need cleanup

Spike tasks

  1. Auth: enable MCP server + OAuth for the account; list tools from a tiny MCP client.
  2. Cross-visibility test: create a runtime via MCP, then check whether colab sessions/status (CLI) sees it and whether colab drivemount -s can attach. If yes, a hybrid (MCP lifecycle+exec, CLI for Drive) is viable; if no, keep v0 CLI-only and use MCP only for metadata.
  3. Long-run semantics: start execute_code with a stable executionId, disconnect, reattach after 10 min; measure whether training keeps running and output resumes.
  4. File bridge: cheapest way to persist a small artifact (mlflow.db) — base64 in execute_code vs gcloud storage vs CLI upload on the same runtime.

Deliverable

docs/mcp-spike.md: auth steps, tool matrix, cross-visibility answer, long-run reattach result, recommendation (adapter? hybrid? skip).

Google now ships a Colab API MCP server: `https://colaboratory.googleapis.com/mcp` (v1beta). Tools: `list_runtime_specs`, `create_runtime`, `get_runtime`, `list_runtimes`, `delete_runtime`, `create_session`, `list_sessions`, `delete_session`, `execute_code`, `get_subscription`. Reference: https://developers.google.com/colab/api/reference/mcp ## Why it might be better than CLI shelling - structured runtime/session lifecycle; `get_subscription` gives the plan tier - `execute_code` streams stdout/stderr and is **resumable via `executionId`** (600 s stream deadline, reattach) - no CLI text parsing ## Why it is not enough (yet) - **no file upload/download, no Drive mount, no SSH** — only text results; files stay on the VM - separate Google Cloud MCP OAuth setup; v1beta; `create_runtime` is rate-limited - sessions hold kernel memory; abandoned sessions need cleanup ## Spike tasks 1. Auth: enable MCP server + OAuth for the account; list tools from a tiny MCP client. 2. **Cross-visibility test**: create a runtime via MCP, then check whether `colab sessions/status` (CLI) sees it and whether `colab drivemount -s` can attach. If yes, a hybrid (MCP lifecycle+exec, CLI for Drive) is viable; if no, keep v0 CLI-only and use MCP only for metadata. 3. Long-run semantics: start `execute_code` with a stable `executionId`, disconnect, reattach after 10 min; measure whether training keeps running and output resumes. 4. File bridge: cheapest way to persist a small artifact (mlflow.db) — base64 in execute_code vs gcloud storage vs CLI upload on the same runtime. ## Deliverable `docs/mcp-spike.md`: auth steps, tool matrix, cross-visibility answer, long-run reattach result, recommendation (adapter? hybrid? skip).
dsh added this to the v1 - parallel + MCP milestone 2026-11-11 20:18:54 +00:00
Author
Owner

Adapter delivered ahead of the spike in f414adc; live verification still open.

  • mcpEnabled (default false) connects to https://colaboratory.googleapis.com/mcp via Streamable HTTP, discovers tools, and registers them as mcp__colab__<raw> through createMcpToolDefinition; colab_mcp_refresh re-lists and swaps registrations, so future server tools need no plugin release
  • auth: bearer (DSH credential ref) or command (/bin/sh -c, 10 s timeout, 10 min cache); tokens never appear in status, results, errors, or logs
  • colab_mcp_status / colab_mcp_refresh always registered; mcpFailOnStartupError controls activation behavior
  • docs/mcp-spike.md records the 10-tool matrix, auth setup, risks, and the hybrid recommendation (CLI for lifecycle/Drive/artifacts, MCP for structured runtime/session/exec)
  • 23 offline tests with a fake MCP client; note: publicToolName is declared but not exported at runtime by dsh-mcp-client@0.2.2-rc.1, so a pinned copy lives in lib/mcp/selection.js

Remaining for this issue: on a real account, verify auth, CLI<->MCP cross-visibility, execute_code reattach across a restart, and cleanup of abandoned sessions.

Adapter delivered ahead of the spike in `f414adc`; live verification still open. - `mcpEnabled` (default false) connects to `https://colaboratory.googleapis.com/mcp` via Streamable HTTP, discovers tools, and registers them as `mcp__colab__<raw>` through `createMcpToolDefinition`; `colab_mcp_refresh` re-lists and swaps registrations, so future server tools need no plugin release - auth: `bearer` (DSH credential ref) or `command` (`/bin/sh -c`, 10 s timeout, 10 min cache); tokens never appear in status, results, errors, or logs - `colab_mcp_status` / `colab_mcp_refresh` always registered; `mcpFailOnStartupError` controls activation behavior - `docs/mcp-spike.md` records the 10-tool matrix, auth setup, risks, and the hybrid recommendation (CLI for lifecycle/Drive/artifacts, MCP for structured runtime/session/exec) - 23 offline tests with a fake MCP client; note: `publicToolName` is declared but not exported at runtime by `dsh-mcp-client@0.2.2-rc.1`, so a pinned copy lives in `lib/mcp/selection.js` Remaining for this issue: on a real account, verify auth, CLI<->MCP cross-visibility, `execute_code` reattach across a restart, and cleanup of abandoned sessions.
Sign in to join this conversation.
No description provided.