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 & Code Sandboxs

Transport Options

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

Document backends

Where the notebook documents live. Execution is a separate choice, made with --sandbox-variant.

Document backend	Description	Configuration
jupyter (default)	Standard JupyterLab/Hub	`--document-provider jupyter`
datalayer	Enterprise hosting	`--document-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 Authentication 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`	`CODE_SANDBOX_URL` value (`http://localhost:8888` if both unset)
`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`
`DOCUMENT_PROVIDER`	Which backend holds the notebook documents	`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-server` / `kaggle` / `monty` / `google-colab` / `modal` / `docker` / `eval` / `daytona` / `e2b` / `coreweave` / `cloudflare` / `datalayer`	`jupyter-server`
`CODE_SANDBOX_PROXY_TOKEN`	Proxy token used by the `google-colab` sandbox variant (`colab-runtime-proxy-token`)	`ya29...`	`None`
`CODE_SANDBOX_CHANNELS_URL`	For the `kaggle` and `google-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. Only `coreweave`, `datalayer`, `daytona`, `kaggle` and `modal` have a GPU; setting it for a variant that has none is refused when the sandbox starts, rather than quietly running on a CPU, so leave it unset for those. Modal/Datalayer examples: `T4`, `A10G`, `A100`, `H100`. Daytona examples: `H100`, `H200`, `RTX-4090`. CoreWeave example: `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-server engine against a Jupyter Server (SANDBOX_VARIANT=jupyter-server). 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-server 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]`	—
`google-colab`	Google Colab code sandbox	`jupyter-mcp-server[google-colab]` (or base install)	`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`
`daytona`	Daytona cloud sandbox	`jupyter-mcp-server[daytona]`	`DAYTONA_API_KEY`, or `DAYTONA_JWT_TOKEN` + `DAYTONA_ORGANIZATION_ID`. Optional accelerator: `SANDBOX_GPU`.
`e2b`	E2B sandbox	`jupyter-mcp-server[e2b]`	`E2B_API_KEY`. Optional: `E2B_DOMAIN`.
`coreweave`	CoreWeave sandbox	`jupyter-mcp-server[coreweave]`	`CWSANDBOX_API_KEY`. Optional: `CWSANDBOX_BASE_URL`, accelerator `SANDBOX_GPU`.
`cloudflare`	Cloudflare sandbox, reached through the sandbox bridge Worker	`jupyter-mcp-server[cloudflare]`	`CLOUDFLARE_SANDBOX_API_URL`, `CLOUDFLARE_SANDBOX_API_KEY`

Example: Google Colab engine

SANDBOX_VARIANT=google-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

Example: Daytona engine

SANDBOX_VARIANT=daytona
DAYTONA_API_KEY=your-daytona-api-key
# ...or a JWT token, which is read with the organization it belongs to:
# DAYTONA_JWT_TOKEN=your-daytona-jwt-token
# DAYTONA_ORGANIZATION_ID=your-daytona-organization-id
SANDBOX_GPU=H100

Example: E2B engine

SANDBOX_VARIANT=e2b
E2B_API_KEY=your-e2b-api-key
# E2B_DOMAIN only when the deployment is not the default e2b.dev:
# E2B_DOMAIN=your-e2b-domain

Example: CoreWeave engine

SANDBOX_VARIANT=coreweave
CWSANDBOX_API_KEY=your-coreweave-api-key
SANDBOX_GPU=H100
# CWSANDBOX_BASE_URL only when the endpoint is not the default https://api.cwsandbox.com:
# CWSANDBOX_BASE_URL=https://api.cwsandbox.com

Example: Cloudflare engine

Cloudflare's SDK is a TypeScript Workers binding, which a Python process cannot hold, so this engine talks to the sandbox bridge — a reference Worker Cloudflare publishes that exposes the SDK over HTTP. Deploy it once:

npm create cloudflare -- sandbox-bridge \
  --template=cloudflare/sandbox-sdk/bridge/worker

The deployment returns the bridge's workers.dev URL and generates the key it accepts. Both are required:

SANDBOX_VARIANT=cloudflare
CLOUDFLARE_SANDBOX_API_URL=https://sandbox-bridge.your-subdomain.workers.dev
CLOUDFLARE_SANDBOX_API_KEY=your-bridge-api-key

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)
  --document-provider [jupyter|datalayer]
                                      Document backend holding the notebooks (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-server (default), kaggle, google-colab, monty, modal, docker, eval, daytona, e2b, coreweave, cloudflare, datalayer
  --code-sandbox-proxy-token TEXT          Proxy token for the google-colab sandbox variant (default: None)
  --code-sandbox-channels-url TEXT         WebSocket channels URL for the kaggle or google-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:
  --document-provider [jupyter|datalayer]
                                      Document backend holding the notebooks (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 \
  --document-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 & Code Sandboxs​

Transport Options​

Document backends​

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​

Example: Daytona engine​

Example: E2B engine​

Example: CoreWeave engine​

Example: Cloudflare 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​