Jupyterlab Collab Mcp Setup

---
name: jupyterlab-collab-mcp-setup
description: >-
  Set up and verify the jupyterlab-collab-mcp MCP server so an agent can read/edit/execute Jupyter notebooks with real-time collaboration. Use when the user says 'connect to the jupyter MCP server', 'check the jupyterlab collab mcp', 'jlabx extensions aren't working', 'verify the MCP server is installed', the agent has no jupyter MCP tools despite expecting them, or notebook edits via MCP fail or return connection errors. THREE-LAYER architecture (opencode <-stdio-> MCP server <-y-websocket-> JupyterLab), three independent break points: (1) jlabx is a LAUNCHER, not the MCP server; (2) jupyter-collaboration must be installed in the SAME env JupyterLab runs from; (3) the MCP server must be registered in opencode.json mcp config (no auto-discovery; restart after changes). Verification: (a) 'jupyter server extension list' shows jupyter_server_ydoc enabled, (b) opencode.json has the jupyter entry, (c) the session actually has jupyter MCP tools. Full gotchas and the confirmed-working config in the body.
created_at: "2026-07-14"
---

# Jupyterlab Collab Mcp Setup

Set up and verify the jupyterlab-collab-mcp MCP server so an opencode (or Claude Code) agent can read/edit/execute Jupyter notebooks with real-time collaboration. Use when the user says 'connect to the jupyter MCP server', 'check the jupyterlab collab mcp', 'jlabx extensions aren't working', 'verify the MCP server is installed', the agent has no jupyter MCP tools despite the user expecting them, notebook edits via MCP fail or return connection errors, OR you need to debug why the agent cannot reach JupyterLab through the MCP server. Covers the THREE-LAYER architecture and the three gotchas that each independently break the connection: (1) jlabx is a LAUNCHER (uv tool install jlabx) that starts JupyterLab with collaboration enabled — it is NOT the MCP server itself; confusing the two wastes turns. (2) jupyter-collaboration (the jupyter-server extension providing y-websocket RTC) MUST be installed in the SAME env that JupyterLab runs from (e.g. the project's pixi env via 'pixi add jupyter-collaboration') — the MCP server connects to JupyterLab via y-websocket, which jupyter-collaboration provides; without it the server cannot reach the notebook. (3) The MCP server must be registered in opencode.json under mcp (or the equivalent client config) — opencode does NOT auto-discover stdio MCP servers. Architecture: opencode <-stdio-> MCP server (npx jupyterlab-collab-mcp) <-y-websocket-> JupyterLab (localhost). The doc URL https://ianhuntisaak.com/jupyterlab-collab-mcp/ is DOCS, NOT an HTTP endpoint you connect to. Confirmed-working opencode.json entry: {"jupyter": {"command": ["npx", "jupyterlab-collab-mcp"], "enabled": true, "type": "local"}}. Verification procedure (3 surfaces, all must pass): (a) 'jupyter server extension list' shows jupyter_server_ydoc as enabled (NOT jupyter_collaboration — that package is a lab frontend extension, not a server extension; see server-extension-name-gotcha section); (b) opencode.json mcp section contains the jupyter entry; (c) the agent session actually has jupyter MCP tools available (restart opencode after config changes — MCP servers load at startup). When debugging, check all three in order — a single broken layer produces a misleading 'cannot connect' symptom. Discovered 2026-07-14 setting up jupyterlab-collab-mcp on the xarray-tutorial repo (pixi env).

## Instructions

TODO: Add specific instructions based on observed patterns.

## server-extension-name-gotcha

- CRITICAL CORRECTION to verification step (a): 'jupyter server extension list' does NOT show 'jupyter_collaboration' — it shows 'jupyter_server_ydoc' (v2.4.x) and 'jupyter_server_fileid' (v0.9.x), which are the DEPENDENCIES of jupyter-collaboration that ARE server extensions. The package 'jupyter_collaboration' is a JupyterLab FRONTEND/lab extension + metapackage, NOT a server extension module. Consequence: 'jupyter server extension enable jupyter_collaboration' FAILS with 'Validation failed: The module jupyter_collaboration could not be found. Are you sure the extension is installed?' — this is EXPECTED, not a bug; do NOT waste turns debugging it or trying to force-enable. The RTC/y-websocket backend the MCP server needs is provided by jupyter_server_ydoc, which auto-enables on install. CORRECTED verification step (a): run 'jupyter server extension list' and confirm jupyter_server_ydoc is 'ok' (enabled) and jupyter_server_fileid is present — that is the signal that jupyter-collaboration installed correctly. Do NOT grep for 'jupyter_collaboration' in the extension list (it will never appear there). Discovered 2026-07-14 on xarray-tutorial (pixi env) where pixi add jupyter-collaboration pulled in jupyter_server_ydoc 2.4.1 + jupyter_server_fileid 0.9.2 as deps, both auto-enabled, while the explicit enable of jupyter_collaboration itself failed validation.