Configuration

Overview

The Jupyter MCP Server supports flexible configuration through environment variables and command-line options to accommodate different deployment scenarios from simple local setups to complex distributed environments.

Server Modes

The server automatically detects the appropriate mode based on deployment context:

Mode	Description	When Used
MCP_SERVER	Standalone server connecting via HTTP	Docker, remote deployments
JUPYTER_SERVER	Runs as Jupyter extension with direct API access	Local deployments, high-performance

JupyterLab Mode

Environment Variable: JUPYTERLAB=true (default)

Enabled: Enhanced UI tools, notebook_run-all-cells tool
Disabled: Basic operations only, headless usage

Open Notebook in UI

Environment Variable: OPEN_NOTEBOOK_IN_UI=false (default)

When enabled together with JupyterLab mode, use_notebook also opens the notebook in the JupyterLab UI, which activates its tab. It is off by default so that notebooks used over MCP do not pull the focus away from the tab you are working in.

Transport & Providers

Transport Options

Transport	Use Case	Configuration
STDIO (default)	Desktop apps, Docker	`--transport stdio`
Streamable HTTP	Web apps, multiple clients	`--transport streamable-http --port 4040`

Providers

Provider	Description	Configuration
jupyter (default)	Standard JupyterLab/Hub	`--provider jupyter`
datalayer	Enterprise hosting	`--provider datalayer`

Environment Variables

The server supports both simplified and advanced configuration approaches:

Simplified Configuration (Recommended)

For most users with standard JupyterLab setups:

Variable	Description	Example	Default	Required
`JUPYTER_URL`	URL of your Jupyter server	`http://localhost:8888`	`http://localhost:8888`	No
`JUPYTER_TOKEN`	Authentication token for Jupyter server	`my-secret-token`	`None`	No*
`JUPYTER_PASSWORD`	Password for Jupyter server authentication (alternative to token)	`my-password`	`None`	No*
`DOCUMENT_ID`	Default notebook path (relative to Jupyter root)	`notebook.ipynb`	`None`	No
`ALLOWED_JUPYTER_MCP_TOOLS`	Comma-separated list of jupyter-mcp-tools to enable	`notebook_run-all-cells,notebook_get-selected-cell`	`notebook_run-all-cells,notebook_get-selected-cell`	No
`ALLOW_IMG_OUTPUT`	Enable multimodal image support	`true` / `false`	`true`	No

*At least one of JUPYTER_TOKEN or JUPYTER_PASSWORD is required when connecting to a secured Jupyter server. They are independent authentication mechanisms — a server may have both configured, and supplying either one is sufficient to connect. When both are provided to the MCP server, password authentication takes precedence. See Security for details on when to use each.

Advanced Configuration (Complex Deployments)

For deployments requiring granular control over document storage and code sandbox execution:

Document Storage Variables

Variable	Description	Example	Default
`DOCUMENT_URL`	URL for notebook file operations	`http://notebook-storage:8888`	`http://localhost:8888`
`DOCUMENT_TOKEN`	Authentication for document operations	`storage-access-token`	`None`
`DOCUMENT_PASSWORD`	Password for document server authentication (alternative to token)	`storage-password`	`None`
`DOCUMENT_ID`	Notebook path/ID	`shared/analysis.ipynb`	`None`

Code Sandbox Execution Variables

Variable	Description	Example	Default
`CODE_SANDBOX_URL`	URL for kernel/execution operations	`http://compute-cluster:8888`	`http://localhost:8888`
`CODE_SANDBOX_TOKEN`	Authentication for code sandbox operations	`compute-access-token`	`None`
`CODE_SANDBOX_PASSWORD`	Password for code sandbox server authentication (alternative to token)	`compute-password`	`None`
`CODE_SANDBOX_ID`	Specific kernel ID to use	`kernel-abc123`	`None`

MCP Client Authentication

Variable	Description	Example	Default
`MCP_TOKEN`	Token for authenticating MCP clients (Bearer scheme). Required for `streamable-http` unless `INSECURE_MCP_NOAUTH` is set.	`mcp-client-secret`	—
`INSECURE_MCP_NOAUTH`	Allow `streamable-http` without MCP client authentication. Not recommended for production.	`true`	`false`

Additional Configuration Variables

Variable	Description	Example	Default
`START_NEW_CODE_SANDBOX`	Create new code sandbox vs use existing	`true` / `false`	`false`
`PROVIDER`	Provider type for document and code sandbox	`jupyter` / `datalayer`	`jupyter`
`TRANSPORT`	Transport method for MCP	`stdio` / `streamable-http`	`stdio`
`PORT`	Port for streamable HTTP transport	`4040`	`4040`
`RECONNECT_INTERVAL`	Seconds before retrying a dropped kernel WebSocket connection. `0` disables auto-reconnect.	`5`	`0`
`JUPYTER_MCP_EXECUTION_TIMEOUT`	Default timeout in seconds for code execution, used when a tool call does not pass its own timeout. Must be greater than `0`.	`300`	`120`
`JUPYTER_MCP_MAX_EXECUTION_TIMEOUT`	Maximum timeout in seconds a tool call may request for code execution. Must be greater than `0`.	`7200`	`3600`
`JUPYTERLAB`	Enable JupyterLab mode	`true` / `false`	`true`
`OPEN_NOTEBOOK_IN_UI`	Open the notebook in the JupyterLab UI on `use_notebook`, activating its tab	`true` / `false`	`false`
`JUPYTER_MCP_OTEL_FILE`	Path for OpenTelemetry span export (JSONL)	`/tmp/spans.jsonl`	`None`
`SANDBOX_VARIANT`	Code sandbox variant (see Sandbox Variants)	`jupyter` / `kaggle` / `monty` / `colab` / `modal` / `docker` / `eval` / `datalayer`	`jupyter`
`CODE_SANDBOX_PROXY_TOKEN`	Proxy token used by the `colab` sandbox variant (`colab-code-sandbox-proxy-token`)	`ya29...`	`None`
`CODE_SANDBOX_CHANNELS_URL`	For the `kaggle` and `colab` engines, notebook session websocket channels URL used to derive `CODE_SANDBOX_URL` and `CODE_SANDBOX_ID`	`wss://.../api/kernels/.../channels?...`	`None`
`SANDBOX_ENVIRONMENT`	Environment name for cloud sandboxes (Datalayer/Modal)	`python-cpu-env`	`None`
`SANDBOX_GPU`	GPU flavor / accelerator for supported variants. Modal/Datalayer examples: `T4`, `A10G`, `A100`, `H100`. Kaggle batch examples: `NvidiaTeslaT4`, `NvidiaTeslaP100` (aliases `T4`, `P100` also supported).	`T4`	`None`

Sandbox Variants

By default the server executes code through the code-sandboxes jupyter engine against a Jupyter Server (SANDBOX_VARIANT=jupyter). Setting SANDBOX_VARIANT to any other value routes execution through the code-sandboxes package via a sandbox-backed plain kernel client (when the selected variant exposes one), so the same notebook tools can run code on additional backends.

Sandbox functionality is provided by the optional jupyter_mcp_sandboxes extension. Install it (pip install jupyter_mcp_sandboxes) to expose the sandbox lifecycle tools and use any non-jupyter sandbox variant.

Variant	Description	Extra install	Key variables
`jupyter` (default)	Jupyter Server via `code-sandboxes` (`jupyter` engine)	—	`JUPYTER_URL`, `JUPYTER_TOKEN` (or `CODE_SANDBOX_` + `DOCUMENT_`)
`kaggle`	Kaggle notebook code sandbox	`jupyter-mcp-server[kaggle]`	Default batch mode: `KAGGLE_API_TOKEN` (or Kaggle credentials). Interactive mode: `CODE_SANDBOX_URL` (+ `KAGGLE_API_TOKEN`, or `CODE_SANDBOX_ID`). Optional accelerator: `SANDBOX_GPU`.
`monty`	In-process secure Python interpreter (Monty)	`jupyter-mcp-server[monty]`	—
`colab`	Google Colab code sandbox	`jupyter-mcp-server[colab]`	`CODE_SANDBOX_URL`, `CODE_SANDBOX_ID`, `CODE_SANDBOX_PROXY_TOKEN`
`modal`	Modal cloud sandbox	`jupyter-mcp-server[modal]`	Modal credentials
`docker`	Local Docker container running Jupyter	`jupyter-mcp-server[sandboxes]`	—
`eval`	In-process `exec()` (development only)	`jupyter-mcp-server[sandboxes]`	—
`datalayer`	Datalayer cloud code sandbox	`jupyter-mcp-server[sandboxes]`	`CODE_SANDBOX_URL`, `CODE_SANDBOX_TOKEN`, `SANDBOX_ENVIRONMENT`

Example: Google Colab engine

SANDBOX_VARIANT=colab
CODE_SANDBOX_URL=https://8080-m-s-kkb-...-d.us-east1-0.prod.colab.dev
CODE_SANDBOX_ID=a1b2c3d4-....
CODE_SANDBOX_PROXY_TOKEN=ya29....

Example: Kaggle engine

SANDBOX_VARIANT=kaggle
# Default batch mode (no code sandbox URL required):
KAGGLE_API_TOKEN=...
SANDBOX_GPU=T4
# Interactive mode (optional):
# CODE_SANDBOX_URL=https://kkb-production.jupyter-proxy.kaggle.net/k/12345678/eyJ.../proxy
# ...or connect to an existing kernel by also setting CODE_SANDBOX_ID:
# CODE_SANDBOX_ID=11e073f0-e82d-4029-be8d-3918f7ed1a9e

Kaggle accelerator values include NvidiaTeslaP100, NvidiaTeslaT4, NvidiaTeslaT4Highmem, NvidiaL4, NvidiaL4X1, NvidiaTeslaA100, NvidiaH100, and NvidiaRtxPro6000. Aliases like P100 and T4 are accepted.

Example: Monty engine

SANDBOX_VARIANT=monty

SANDBOX_VARIANT=modal
# Modal credentials via `modal token new` or MODAL_TOKEN_ID / MODAL_TOKEN_SECRET

Configuration Priority

Variables are resolved in this order:

Individual variables (DOCUMENT_*, CODE_SANDBOX_*) - highest priority
Simplified variables (JUPYTER_*) - fallback
Default values - when no variables are set

This applies to tokens, passwords, and URLs alike. For example, CODE_SANDBOX_PASSWORD takes precedence over JUPYTER_PASSWORD for code sandbox server authentication.

When both a password and a token are configured for the same server, password authentication takes precedence and the token is ignored.

Configuration Examples

Standard JupyterLab Setup

JUPYTER_URL=http://localhost:8888
JUPYTER_TOKEN=my-token
DOCUMENT_ID=my-notebook.ipynb
ALLOWED_JUPYTER_MCP_TOOLS=notebook_run-all-cells,notebook_get-selected-cell
ALLOW_IMG_OUTPUT=true

JupyterHub with Separate Services

DOCUMENT_URL=http://hub.example.com:8000
DOCUMENT_TOKEN=hub-api-token
CODE_SANDBOX_URL=http://user-server:8888
CODE_SANDBOX_TOKEN=user-server-token
DOCUMENT_ID=shared/analysis.ipynb

Distributed Computing Setup

DOCUMENT_URL=http://file-server:8888
DOCUMENT_TOKEN=file-access-token
CODE_SANDBOX_URL=http://compute-node:8888
CODE_SANDBOX_TOKEN=compute-access-token
ALLOW_IMG_OUTPUT=false

Password-Protected Jupyter Server

JUPYTER_URL=http://localhost:8888
JUPYTER_PASSWORD=my-jupyter-password
DOCUMENT_ID=my-notebook.ipynb

Development Setup

JUPYTER_URL=http://localhost:8888
JUPYTER_TOKEN=dev-token
# DOCUMENT_ID omitted

Command Line Options

For advanced use cases, you can configure the server using command-line flags:

jupyter mcp start --help

Usage: jupyter mcp start [OPTIONS]

Options:
  --transport [stdio|streamable-http]  Transport type (default: stdio)
  --provider [jupyter|datalayer]      Provider type (default: jupyter)
  --jupyterlab BOOLEAN               Enable JupyterLab mode (default: true)
  --code-sandbox-url TEXT                  Runtime URL for kernel operations (default: None)
  --code-sandbox-token TEXT                Runtime authentication token (default: None)
  --code-sandbox-password TEXT             Password for code sandbox Jupyter server authentication (default: None)
  --mcp-token TEXT                    Token for authenticating MCP clients (required unless --insecure-mcp-noauth)
  --insecure-mcp-noauth               Allow streamable-http without MCP client auth (not recommended)
  --code-sandbox-id TEXT                   Specific kernel ID to use (default: None)
  --start-new-code-sandbox BOOLEAN         Create new code sandbox vs use existing (default: true)
  --document-url TEXT                 Document URL for notebook operations (default: None)
  --document-id TEXT                  Notebook path/ID (default: None)
  --document-token TEXT               Document authentication token (default: None)
  --document-password TEXT            Password for document Jupyter server authentication (default: None)
  --jupyter-url TEXT                  Jupyter URL as default for both document and code sandbox URLs (default: None)
  --jupyter-token TEXT                Jupyter token as default for both document and code sandbox tokens (default: None)
  --jupyter-password TEXT             Shared password for both code sandbox and document servers (default: None)
  --allowed-jupyter-mcp-tools TEXT    Comma-separated list of jupyter-mcp-tools to enable (default: notebook_run-all-cells,notebook_get-selected-cell)
  --reconnect-interval INTEGER         Seconds before retrying a dropped kernel WebSocket connection (default: 0)
  --execution-timeout INTEGER RANGE   Default timeout in seconds for code execution when a tool call passes no timeout (default: 120)
  --max-execution-timeout INTEGER RANGE
                                      Maximum timeout in seconds a tool call may request (default: 3600)
  --otel-file TEXT                    Path for OpenTelemetry span export as JSONL (default: None)
  --sandbox-variant TEXT             Code sandbox variant: jupyter (default), kaggle, colab, monty, modal, docker, eval, datalayer
  --code-sandbox-proxy-token TEXT          Proxy token for the colab sandbox variant (default: None)
  --code-sandbox-channels-url TEXT         WebSocket channels URL for the kaggle or colab sandbox variants (default: None)
  --sandbox-environment TEXT          Environment name for cloud sandboxes (default: None)
  --sandbox-gpu TEXT                  GPU flavor / accelerator for supported sandbox variants (default: None)
  --port INTEGER                      Port for streamable-http transport (default: 4040)

Additional Commands

The server also supports additional commands for advanced workflows:

Connect Command

jupyter mcp connect --help

Usage: jupyter mcp connect [OPTIONS]

Connect a Jupyter MCP Server to a document and a code sandbox.

Options:
  --provider [jupyter|datalayer]      Provider type (default: jupyter)
  --jupyterlab BOOLEAN               Enable JupyterLab mode (default: true)
  --code-sandbox-url TEXT                  Runtime URL for kernel operations (default: None)
  --code-sandbox-token TEXT                Runtime authentication token (default: None)
  --mcp-token TEXT                    MCP token used to authenticate to /api/connect (Bearer)
  --code-sandbox-id TEXT                   Specific kernel ID to use (default: None)
  --document-url TEXT                 Document URL for notebook operations (default: None)
  --document-id TEXT                  Notebook path/ID (default: None)
  --document-token TEXT               Document authentication token (default: None)
  --jupyter-url TEXT                  Jupyter URL as default for both document and code sandbox URLs (default: None)
  --jupyter-token TEXT                Jupyter token as default for both document and code sandbox tokens (default: None)
  --reconnect-interval INTEGER        Seconds before retrying a dropped kernel WebSocket connection (default: 0)
  --execution-timeout INTEGER RANGE   Default timeout in seconds for code execution when a tool call passes no timeout (default: 120)
  --max-execution-timeout INTEGER RANGE
                                      Maximum timeout in seconds a tool call may request (default: 3600)
  --jupyter-mcp-server-url TEXT       URL of the Jupyter MCP Server to connect to (default: http://localhost:4040)

Stop Command

jupyter mcp stop --help

Usage: jupyter mcp stop [OPTIONS]

Stop a running Jupyter MCP Server.

Options:
  --jupyter-mcp-server-url TEXT       URL of the Jupyter MCP Server to stop (default: http://localhost:4040)
  --mcp-token TEXT                    MCP token used to authenticate to /api/stop (Bearer)

Usage Examples

jupyter mcp start \
  --transport streamable-http \
  --jupyter-url http://localhost:8888 \
  --jupyter-token MY_TOKEN \
  --allowed-jupyter-mcp-tools "notebook_run-all-cells,notebook_get-selected-cell" \
  --port 4040

Advanced Usage

Connecting to Existing Runtime

Start server without creating new code sandbox:

jupyter mcp start \
  --transport streamable-http \
  --code-sandbox-url http://localhost:8888 \
  --code-sandbox-token MY_TOKEN \
  --start-new-code-sandbox false

Then connect via endpoint:

jupyter mcp connect \
  --provider datalayer \
  --document-url <url> \
  --document-id <document> \
  --document-token <token> \
  --code-sandbox-url <url> \
  --code-sandbox-id <code-sandbox-id> \
  --code-sandbox-token <token> \
  --jupyter-mcp-server-url http://localhost:4040

Multimodal Output Support

The server supports multimodal output, allowing AI agents to directly receive and analyze visual content such as images and charts generated by code execution.

Supported Output Types

Text Output: Standard text output from code execution
Image Output: PNG images generated by matplotlib, seaborn, plotly, and other visualization libraries
Error Output: Error messages and tracebacks

Environment Variable Configuration

Control multimodal output behavior using environment variables:

`ALLOW_IMG_OUTPUT`

Controls whether to return actual image content or text placeholders.

Default: true
Values: true, false, 1, 0, yes, no, on, off, enable, disable, enabled, disabled

Output Behavior

When `ALLOW_IMG_OUTPUT=true` (Default)

Images are returned as ImageContent objects with actual PNG data
AI agents can directly analyze visual content
Supports advanced multimodal reasoning

When `ALLOW_IMG_OUTPUT=false`

Images are returned as text placeholders: "[Image Output (PNG) - Image display disabled]"
Maintains backward compatibility with text-only LLMs
Reduces bandwidth and token usage

Use Cases

Data Visualization Analysis:

import matplotlib.pyplot as plt
import pandas as pd

df = pd.read_csv('sales_data.csv')
df.plot(kind='bar', x='month', y='revenue')
plt.title('Monthly Revenue')
plt.show()
# AI can now "see" and analyze the chart content

Machine Learning Model Visualization:

import matplotlib.pyplot as plt

# Plot training curves
plt.plot(epochs, train_loss, label='Training Loss')
plt.plot(epochs, val_loss, label='Validation Loss')
plt.legend()
plt.show()
# AI can evaluate training effectiveness from the visual curves

Overview​

Server Modes​

JupyterLab Mode​

Open Notebook in UI​

Transport & Providers​

Transport Options​

Providers​

Environment Variables​

Simplified Configuration (Recommended)​

Advanced Configuration (Complex Deployments)​

Document Storage Variables​

Code Sandbox Execution Variables​

MCP Client Authentication​

Additional Configuration Variables​

Sandbox Variants​

Example: Google Colab engine​

Example: Kaggle engine​

Example: Monty engine​

Example: Modal engine​

Configuration Priority​

Configuration Examples​

Standard JupyterLab Setup​

JupyterHub with Separate Services​

Distributed Computing Setup​

Password-Protected Jupyter Server​

Development Setup​

Command Line Options​

Additional Commands​

Connect Command​

Stop Command​

Usage Examples​

Advanced Usage​

Connecting to Existing Runtime​

Multimodal Output Support​

Supported Output Types​

Environment Variable Configuration​

ALLOW_IMG_OUTPUT​

Output Behavior​

When ALLOW_IMG_OUTPUT=true (Default)​

When ALLOW_IMG_OUTPUT=false​

Use Cases​