Releases

Migration Guide to 1.3.2

Version 1.3.2 renames provider to document_provider, so that the name says what the option actually selects.

It only ever chose where the notebook documents live — jupyter for the collaboration API of a Jupyter Server, datalayer for the Datalayer spacer. Where the code runs is a separate choice, made with --sandbox-variant. The old name, and its help text, suggested one option governed both.

Nothing breaks in 1.3.2

The former names are deprecated, not removed. --provider is still accepted as an alias, PROVIDER is still read, and a /connect payload carrying "provider" is still understood. Migrate when convenient.

Who Should Migrate

• End users passing --provider or setting PROVIDER, which in practice means anyone pointing the server at Datalayer-hosted documents.
• Operators whose manifests, wrapper scripts or MCP client configurations carry PROVIDER.
• Anyone calling the /connect endpoint or the connect_to_jupyter tool with a provider field.

Change Summary

• Use document_provider names everywhere instead of provider names.
• The accepted values are unchanged: jupyter (default) and datalayer.
• Execution backends keep their own option, --sandbox-variant / SANDBOX_VARIANT.
• Nothing has to change immediately: the old names still work in this version.

Rename Matrix

Old (pre-1.3.2)	New (1.3.2+)
provider	document_provider
PROVIDER	DOCUMENT_PROVIDER
--provider	--document-provider
"provider" in the /connect payload	"document_provider"
provider argument of connect_to_jupyter	document_provider

End User Migration

1. Update environment variables

Before:

export PROVIDER=datalayer

After:

export DOCUMENT_PROVIDER=datalayer

2. Update CLI commands

Before:

jupyter mcp start \
	--provider datalayer \
	--document-url <url> \
	--document-token <token>

After:

jupyter mcp start \
	--document-provider datalayer \
	--document-url <url> \
	--document-token <token>

3. Update MCP client configurations

An MCP client passing the variable through its env block needs the new key:

{
  "env": {
    "DOCUMENT_PROVIDER": "datalayer",
    "DOCUMENT_URL": "<url>",
    "DOCUMENT_TOKEN": "<token>"
  }
}

4. Check that document and execution are configured separately

The two axes are independent, and a Datalayer document store does not imply a Datalayer sandbox. State each one:

jupyter mcp start \
	--document-provider datalayer \
	--sandbox-variant datalayer

Known Migration Pitfalls

• Assuming --provider datalayer also moved execution to Datalayer; it never did, and --sandbox-variant is what does.
• Both PROVIDER and DOCUMENT_PROVIDER set to different values in the same environment. The new name wins, which may not be what the older one intended.
• Wrapper scripts updated while CI secrets still carry the old key name.

Recommended Migration Checklist

1. Replace PROVIDER with DOCUMENT_PROVIDER in environments, manifests and CI secrets.
2. Replace --provider with --document-provider in commands and wrappers.
3. Rename provider to document_provider in /connect payloads and tool calls.
4. State --sandbox-variant explicitly wherever execution is not the default Jupyter one.
5. Validate a notebook opens and a cell executes before removing the old names.

For full reference values, see Configuration.

Migration Guide to 1.2.0

Version 1.2.0 completes the terminology migration from runtime to code sandbox.

This is primarily a naming and configuration migration. Execution behavior is the same goal as before: notebooks are stored on a document server and code is executed by a kernel backend. The backend is now consistently called code sandbox across CLI, environment variables, config model, and docs.

Who Should Migrate

• End users running jupyter-mcp-server locally or in CI.
• Operators maintaining shared MCP server deployments (containers, services, platform templates, runbooks).

Breaking Change Summary

• Use code_sandbox names everywhere instead of runtime names.
• Use CODE_SANDBOX_* environment variables and matching CLI flags.
• Use start_new_code_sandbox naming for bootstrap behavior.
• Any custom scripts or wrappers using old runtime names must be updated.

Rename Matrix

Old (pre-1.2.0)	New (1.2.0+)
runtime	code sandbox
RUNTIME_URL	CODE_SANDBOX_URL
RUNTIME_TOKEN	CODE_SANDBOX_TOKEN
RUNTIME_PASSWORD	CODE_SANDBOX_PASSWORD
RUNTIME_ID	CODE_SANDBOX_ID
START_NEW_RUNTIME	START_NEW_CODE_SANDBOX
--runtime-url	--code-sandbox-url
--runtime-token	--code-sandbox-token
--runtime-password	--code-sandbox-password
--runtime-id	--code-sandbox-id
--start-new-runtime	--start-new-code-sandbox

End User Migration

1. Update environment variables

Before:

export RUNTIME_URL=http://localhost:8888
export RUNTIME_TOKEN=MY_TOKEN
export START_NEW_RUNTIME=true

After:

export CODE_SANDBOX_URL=http://localhost:8888
export CODE_SANDBOX_TOKEN=MY_TOKEN
export START_NEW_CODE_SANDBOX=true

2. Update CLI commands

Before:

jupyter-mcp-server \
	--runtime-url http://localhost:8888 \
	--runtime-token MY_TOKEN

After:

jupyter-mcp-server \
	--code-sandbox-url http://localhost:8888 \
	--code-sandbox-token MY_TOKEN

3. Validate split document + code sandbox setups

If you run document storage and execution on different servers, ensure both sides are configured explicitly:

export DOCUMENT_URL=http://notebook-storage:8888
export DOCUMENT_TOKEN=DOC_TOKEN

export CODE_SANDBOX_URL=http://compute-cluster:8888
export CODE_SANDBOX_TOKEN=EXEC_TOKEN

4. Validate auth mode

Token and password auth still work the same way, just with updated names:

• CODE_SANDBOX_TOKEN or CODE_SANDBOX_PASSWORD
• DOCUMENT_TOKEN or DOCUMENT_PASSWORD

When both token and password are supplied, password authentication takes precedence.

Operator Migration

1. Update deployment manifests and templates

Update references in:

• Kubernetes manifests
• Helm values/templates
• Docker Compose files
• systemd units
• CI/CD secrets and variable groups

Recommended approach:

1. Add new CODE_SANDBOX_* variables.
2. Remove old RUNTIME_* variables.
3. Restart workloads and verify MCP health checks.

2. Update startup wrappers and runbooks

Search and replace in operational scripts:

• runtime -> code_sandbox for internal names
• runtime-oriented flags -> --code-sandbox-*

Also update on-call docs and incident runbooks so diagnostics use current naming.

3. Validate service behavior post-cutover

Run these checks after rollout:

1. MCP health endpoint returns healthy status.
2. Kernel listing works (list_kernels).
3. Notebook operations work (use_notebook, read_cell, execute_cell).
4. Reconnect behavior remains as expected (RECONNECT_INTERVAL).

Configuration Examples (1.2.0+)

Single Jupyter server for both document and code sandbox

export JUPYTER_URL=http://localhost:8888
export JUPYTER_TOKEN=MY_TOKEN

Explicit dual-server topology

export DOCUMENT_URL=http://notebook-storage:8888
export DOCUMENT_TOKEN=DOC_TOKEN
export DOCUMENT_ID=shared/analysis.ipynb

export CODE_SANDBOX_URL=http://compute-cluster:8888
export CODE_SANDBOX_TOKEN=EXEC_TOKEN
export START_NEW_CODE_SANDBOX=false

Sandbox variant execution

export SANDBOX_VARIANT=kaggle
export CODE_SANDBOX_CHANNELS_URL=wss://.../api/kernels/.../channels?...
export SANDBOX_GPU=T4

Known Migration Pitfalls

• Old RUNTIME_* names left in environment but ignored by new startup paths.
• Mixed old/new names across microservices causing partial misconfiguration.
• Wrapper scripts updated, but CI secrets still use old key names.
• Documentation drift in internal playbooks and customer onboarding docs.

Recommended Migration Checklist

1. Replace all RUNTIME_* env vars with CODE_SANDBOX_*.
2. Replace all runtime CLI flags with code sandbox flags.
3. Update deployment manifests, secrets, and runbooks.
4. Validate health plus core notebook execution flows.
5. Remove old naming from internal docs to prevent regressions.

For full reference values, see Configuration.

Latest Release

See the latest release notes on the GitHub Releases page.

Older Releases

0.16.x - 13 Oct 2025

• Merge the three execute tools into a single unified tool
• Docs: update readme and contributing
• CI: build Auto Releases CI/CD: #114, #115, #119, #120
• fix negative index
• fix ressources and prompts list
• Refactor: separate and simplify the server.py
• Feat/add JUPYTER_URL and JUPYTER_TOKEN

0.15.x - 08 Oct 2025

• Run as Jupyter Server Extension + Tool registry + Use tool
• simplify tool implementations
• add uvx as alternative MCP server startup method
• document as a Jupyter Extension
• Fix Minor Bugs: #108,#110

0.14.0 - 03 Oct 2025

• Additional Tools & Bug fixes.
• Execute IPython.
• Multi notebook management.

0.13.0 - 25 Sep 2025

• Add multimodal output support for Jupyter cell execution.
• Unify cell insertion functionality.

0.11.0 - 01 Aug 2025

• Rename room to document.

0.10.2 - 17 Jul 2025

• Tools docstring improvements.

0.10.1 - 11 Jul 2025

• CORS Support.

0.10.0 - 07 Jul 2025

• More fixes issues for nbclient stop.

0.9.0 - 02 Jul 2025

• Fix issues with nbmodel stops.

0.6.0 - 01 Jul 2025

• Configuration change, see details on the clients page and server configuration.