### Install Dependencies with Make

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/examples/cli/README.md

Run this command to install all necessary project dependencies.

```bash
make install
```

--------------------------------

### Manual Agent Testing Setup

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/CONTRIBUTING.md

Install necessary Jupyter components and specific versions of Python packages for manual testing.

```bash
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 ipykernel
```

```bash
pip uninstall -y pycrdt datalayer_pycrdt
```

```bash
pip install datalayer_pycrdt==0.12.17
```

--------------------------------

### Start Jupyter MCP Server (Python)

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-streamable-http-standalone/index.mdx

Installs and starts the Jupyter MCP Server using Python, configuring it to use streamable HTTP transport and connect to a Jupyter server.

```bash
pip install jupyter-mcp-server
jupyter-mcp-server start \
  --transport streamable-http \
  --jupyter-url http://localhost:8888 \
  --jupyter-token MY_TOKEN \
  --mcp-token MY_MCP_TOKEN \
  --port 4040
```

--------------------------------

### Start Jupyter MCP Server with Streamable HTTP

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/configuration/index.mdx

Example of starting the Jupyter MCP Server using streamable HTTP transport. Configures Jupyter URL, token, allowed tools, and port.

```bash
jupyter-mcp-server 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
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/CONTRIBUTING.md

Clone the project repository and install the project in editable mode with test dependencies.

```bash
git clone https://github.com/datalayer/jupyter-mcp-server
cd jupyter-mcp-server
```

```bash
# Install the project in editable mode with test dependencies
pip install -e ".[test]"
```

--------------------------------

### Start Local Development Server

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/README.md

Starts a local development server for live previewing changes. Most modifications are reflected without a server restart.

```bash
npm start
```

--------------------------------

### Jupyter MCP Server Start Command Help

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/configuration/index.mdx

Displays help information for the 'jupyter-mcp-server start' command, outlining available options for server configuration.

```bash
jupyter-mcp-server start --help

Usage: jupyter-mcp-server 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)
  --runtime-url TEXT                  Runtime URL for kernel operations (default: None)
  --runtime-token TEXT                Runtime authentication token (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)
  --runtime-id TEXT                   Specific kernel ID to use (default: None)
  --start-new-runtime BOOLEAN         Create new runtime 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)
  --jupyter-url TEXT                  Jupyter URL as default for both document and runtime URLs (default: None)
  --jupyter-token TEXT                Jupyter token as default for both document and runtime tokens (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)
  --otel-file TEXT                    Path for OpenTelemetry span export as JSONL (default: None)
  --port INTEGER                      Port for streamable-http transport (default: 4040)
```

--------------------------------

### Install and Verify uv for MCP Client

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/CONTRIBUTING.md

Install the 'uv' package and verify its version, which is required for setting up the MCP client.

```bash
pip install uv
```

```bash
uv --version
# should be 0.6.14 or higher
```

--------------------------------

### Install UV for Simplified Configuration

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-stdio/index.mdx

Installs the 'uv' package, which is required for the simplified configuration of the Jupyter MCP Server.

```bash
pip install uv
```

```bash
uv --version  # should be 0.6.14 or higher
```

--------------------------------

### Start JupyterLab Server

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-streamable-http-standalone/index.mdx

Command to start the JupyterLab server on a specified port with a custom token for authentication.

```bash
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN
```

--------------------------------

### Start Jupyter with a Token

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/security/index.mdx

Recommended for token-less environments. Start your Jupyter server with a secure token and configure MCP server with the same token.

```bash
jupyter lab --IdentityProvider.token YOUR_SECURE_TOKEN
```

```json
{
  "env": {
    "JUPYTER_TOKEN": "YOUR_SECURE_TOKEN"
  }
}
```

--------------------------------

### Start Full Stack with Make

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/examples/cli/README.md

Launches JupyterLab, Jupyter MCP Server, and the pydantic-ai CLI in one command.

```bash
make start
```

--------------------------------

### Install MCPB CLI Tool

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/mcpb/README.md

Install the MCPB CLI tool globally using npm. This is required before building the bundle.

```bash
npm install -g @anthropic-ai/mcpb
```

--------------------------------

### Start MCP_SERVER Mode

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/ARCHITECTURE.md

Use this command to start the MCP server in standalone mode. Ensure to replace MY_TOKEN with your actual token and adjust URLs and port as needed.

```bash
jupyter-mcp-server start \
  --transport streamable-http \
  --document-url http://localhost:8888 \
  --runtime-url http://localhost:8888 \
  --document-token MY_TOKEN \
  --runtime-token MY_TOKEN \
  --port 4040
```

--------------------------------

### Configure Runtime Settings with Make

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/examples/cli/README.md

Override default settings like tokens and model names when starting the stack.

```bash
MCP_TOKEN=my-mcp-token \
JUPYTER_TOKEN=my-jupyter-token \
MODEL=bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0 \
make start
```

--------------------------------

### Simplified Jupyter Provider Configuration

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-stdio/index.mdx

Use this configuration for a straightforward setup where document storage and runtime execution are handled by the same Jupyter instance. Ensure Docker is installed and the datalayer/jupyter-mcp-server image is available.

```json
{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "JUPYTER_URL",
        "-e", "JUPYTER_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "--network=host",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}
```

--------------------------------

### Start JUPYTER_SERVER Mode (Extension)

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/ARCHITECTURE.md

Use this command to start Jupyter server with the MCP extension enabled. Configure document and runtime URLs to 'local' for direct backend access.

```bash
jupyter server \
  --JupyterMCPServerExtensionApp.document_url=local \
  --JupyterMCPServerExtensionApp.runtime_url=local \
  --JupyterMCPServerExtensionApp.document_id=notebook.ipynb
```

--------------------------------

### Install Dependencies with Conda and Yarn

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/README.md

Installs project dependencies using conda and then yarn. Ensure conda is installed before running.

```bash
conda install yarn
yarn
```

--------------------------------

### Start Jupyter Server for Testing

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/CONTRIBUTING.md

Launch a Jupyter server on a specific port with token authentication and accessible from any IP.

```bash
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0
```

--------------------------------

### Start Standalone MCP Server with Token

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/security/index.mdx

Starts the standalone MCP server with streamable-http transport, requiring a specific token for MCP client authentication.

```bash
jupyter-mcp-server start \
  --transport streamable-http \
  --jupyter-token JUPYTER_SECRET \
  --mcp-token MCP_CLIENT_SECRET
```

--------------------------------

### Install JupyterLab and Dependencies

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-streamable-http-standalone/index.mdx

Installs necessary packages for JupyterLab and real-time collaboration features required for MCP server integration.

```bash
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel pycrdt
```

--------------------------------

### Start Jupyter with Token

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/security/index.mdx

Starts JupyterLab with a token, which is then used for authenticating API requests and MCP server interactions.

```bash
jupyter lab --IdentityProvider.token MY_TOKEN
```

--------------------------------

### Start JupyterLab with MCP Extension

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-streamable-http-extension/index.mdx

Launches JupyterLab with the MCP server extension enabled, specifying a port and authentication token.

```bash
jupyter lab --port 4040 --IdentityProvider.token MY_TOKEN
```

--------------------------------

### Install Jupyter MCP Server and Dependencies

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-streamable-http-extension/index.mdx

Installs the necessary packages for the Jupyter MCP Server extension and real-time collaboration features.

```bash
pip install "jupyter-mcp-server>=0.15.0" "jupyterlab==4.4.1" "jupyter-collaboration==4.0.2" "ipykernel" "pycrdt"
```

--------------------------------

### Install JupyterHub and Generate Config

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/multi-users/index.mdx

Installs JupyterHub using pip and generates its configuration file. This is a foundational step for migrating to a JupyterHub environment.

```bash
pip install jupyterhub
jupyterhub --generate-config
```

--------------------------------

### Start Server Without New Runtime

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/configuration/index.mdx

Starts the Jupyter MCP Server using streamable HTTP transport without creating a new runtime. Requires specifying existing runtime details.

```bash
jupyter-mcp-server start \
  --transport streamable-http \
  --runtime-url http://localhost:8888 \
  --runtime-token MY_TOKEN \
  --start-new-runtime false
```

--------------------------------

### Install jupyter-mcp-tools

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/tools-additional/index.mdx

Install the jupyter-mcp-tools package in your JupyterLab environment to enable enhanced UI integration capabilities.

```bash
pip install jupyter-mcp-tools>=0.1.4
```

--------------------------------

### Install Unofficial Claude Desktop Build for Linux

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/clients/claude_desktop/index.mdx

Use this command to install an unofficial build of Claude Desktop on Linux using Nix. Ensure you allow unfree packages and enable flakes and nix-command experimental features.

```bash
# ⚠️ UNOFFICIAL
# You can also run `make claude-linux`
NIXPKGS_ALLOW_UNFREE=1 nix run github:k3d3/claude-desktop-linux-flake \
  --impure \
  --extra-experimental-features flakes \
  --extra-experimental-features nix-command
```

--------------------------------

### Enable OTel Tracing via Environment Variable

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/hooks/index.mdx

Enable OpenTelemetry tracing by setting the JUPYTER_MCP_OTEL_FILE environment variable before starting the server.

```bash
export JUPYTER_MCP_OTEL_FILE=/tmp/mcp_spans.jsonl
jupyter-mcp-server start ...
```

--------------------------------

### Configure Standard JupyterLab Setup

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/configuration/index.mdx

Set environment variables for a typical JupyterLab deployment. This includes specifying the Jupyter server URL, authentication token, default document ID, allowed tools, and image output support.

```bash
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
```

--------------------------------

### Start Full Stack without Authentication

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/examples/cli/README.md

Use this command for local development to run MCP with disabled authentication.

```bash
make start-noauth
```

--------------------------------

### Enable OTel Tracing via CLI

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/hooks/index.mdx

Enable OpenTelemetry tracing by specifying the output file path for spans when starting the server via the command line interface.

```bash
jupyter-mcp-server start \
  --otel-file /tmp/mcp_spans.jsonl \
  --transport stdio \
  --jupyter-url http://localhost:8888 \
  --jupyter-token MY_TOKEN
```

--------------------------------

### Configure Workspace Settings for Jupyter MCP Server (Simplified)

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/clients/vscode/index.mdx

Place this JSON configuration in a `.vscode/mcp.json` file at your workspace root for simplified, workspace-specific Jupyter MCP Server setup. Restart VS Code if necessary.

```json
{
  "servers": {
    "DatalayerJupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "JUPYTER_URL",
        "-e",
        "JUPYTER_TOKEN",
        "-e",
        "DOCUMENT_ID",
        "-e",
        "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://host.docker.internal:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}
}
```

--------------------------------

### Custom Logging Hook Handler Example

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/hooks/index.mdx

A Python example demonstrating how to create and register a custom hook handler that logs tool call events. The handler is configured not to propagate errors.

```python
from jupyter_mcp_server.hooks import HookEvent, HookRegistry

class LoggingHandler:
    propagate_errors = False  # Don't break tool calls on logging errors

    async def on_event(self, event: HookEvent, **kwargs) -> None:
        if event == HookEvent.BEFORE_TOOL_CALL:
            print(f"Tool called: {kwargs.get('tool_name')}")
        elif event == HookEvent.AFTER_TOOL_CALL:
            error = kwargs.get("error")
            if error:
                print(f"Tool failed: {kwargs.get('tool_name')} - {error}")
            else:
                print(f"Tool completed: {kwargs.get('tool_name')}")

# Register the handler
handler = LoggingHandler()
HookRegistry.get_instance().register(handler)
```

--------------------------------

### Start JupyterLab Server

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/README.md

Launches JupyterLab on port 8888, allowing access from any IP address and setting a custom authentication token. This command is essential for enabling real-time collaboration features.

```bash
# Start JupyterLab on port 8888, allowing access from any IP and setting a token
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0
```

--------------------------------

### Problematic Shared JupyterLab Setup

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/multi-users/index.mdx

Illustrates a problematic setup where multiple user agents connect to a single MCP server and a shared JupyterLab instance, leading to concurrency issues.

```text
❌ PROBLEMATIC SETUP:

User 1 Agent  ─┐
               ├──▶ Single MCP Server ──▶ Shared JupyterLab
User 2 Agent  ─┘      (shared state)       (all users)

Problem: Both users' agents share the same "active notebook" state
```

--------------------------------

### Verify MCP Server Extension Installation

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/multi-users/index.mdx

Command to check if the Jupyter MCP Server extension is enabled within a single-user Jupyter server environment. This confirms successful installation.

```bash
# Inside single-user server
jupyter server extension list
# Should show: jupyter_mcp_server enabled
```

--------------------------------

### Start Jupyter MCP Server (Docker - MacOS/Windows)

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-streamable-http-standalone/index.mdx

Runs the Jupyter MCP Server using Docker on MacOS or Windows, mapping ports and setting environment variables for Jupyter and MCP authentication.

```bash
docker run \
  -e JUPYTER_URL="http://host.docker.internal:8888" \
  -e JUPYTER_TOKEN="MY_TOKEN" \
  -e MCP_TOKEN="MY_MCP_TOKEN" \
  -p 4040:4040 \
  datalayer/jupyter-mcp-server:latest \
  --transport streamable-http
```

--------------------------------

### Create Docker Secret

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/security/index.mdx

Example of creating a Docker secret for sensitive information like API tokens.

```bash
# Create secret
echo "my-secure-token" | docker secret create jupyter_token -
```

--------------------------------

### Start Jupyter MCP Server (Docker - Linux)

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-streamable-http-standalone/index.mdx

Runs the Jupyter MCP Server using Docker on Linux, utilizing host networking and setting environment variables for Jupyter and MCP authentication.

```bash
docker run \
  --network=host \
  -e JUPYTER_URL="http://localhost:8888" \
  -e JUPYTER_TOKEN="MY_TOKEN" \
  -e MCP_TOKEN="MY_MCP_TOKEN" \
  -p 4040:4040 \
  datalayer/jupyter-mcp-server:latest \
  --transport streamable-http
```

--------------------------------

### Start CLI Only (No Auth)

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/examples/cli/README.md

Launches only the pydantic-ai CLI when JupyterLab and MCP are already running in no-auth mode.

```bash
make start-noauth-agent
```

--------------------------------

### Configure HTTPS/TLS for Jupyter

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/security/index.mdx

Example configuration for setting the Jupyter URL with HTTPS and a token. Always use HTTPS in production.

```json
{
  "env": {
    "JUPYTER_URL": "https://jupyter.example.com:8888",
    "JUPYTER_TOKEN": "your-token-here"
  }
}
```

--------------------------------

### Using Prompt Templates

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/prompt/README.md

Follow these steps to use an existing prompt template. Read the README.md in the template directory to understand its purpose, then copy the content from AGENT.md to use as your system prompt.

```text
1. Go to prompt/general/
2. Read the README.md to understand the template's purpose
3. Copy the content from AGENT.md
4. Paste it as your system prompt(e.g. `CLAUDE.md` in Claude Code)
5. Start your session with enhanced context!
```

--------------------------------

### Tool Registration Flow

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/ARCHITECTURE.md

This diagram illustrates the sequence of events from CLI startup to MCP client discovery and invocation of registered tools.

```text
1. CLI startup (CLI.py)
   ↓
2. Configuration parsing and validation
   ↓
3. ServerContext initialization with mode detection
   ↓
4. FastMCP server initialization (server.py)
   ↓
5. Tool instance creation (14 tool implementations)
   ↓
6. @mcp.tool() wrapper registration
   ↓
7. FastMCP internal tool registry
   ↓
8. Dynamic tool discovery via get_registered_tools()
   ↓
9. Extension handlers expose tools via /mcp/tools/list
   ↓
10. MCP clients discover and invoke tools
```

--------------------------------

### Run Project Tests

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/CONTRIBUTING.md

Execute the project's test suite using the provided make command.

```bash
make test
```

--------------------------------

### Makefile Help and Utility Commands

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/examples/cli/README.md

Lists available Makefile targets and provides commands for cleaning the project.

```bash
make help
make start
make start-noauth
make start-noauth-agent
make clean
```

--------------------------------

### Creating a New Prompt Template Directory

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/prompt/README.md

Clone the repository and create a new directory for your prompt template. This sets up the basic structure for your contribution.

```bash
git clone https://github.com/datalayer/jupyter-mcp-server.git
cd jupyter-mcp-server/prompt
mkdir your-use-case/
```

--------------------------------

### Jupyter MCP Server Connect Command Help

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/configuration/index.mdx

Displays help information for the 'jupyter-mcp-server connect' command, detailing options for connecting to documents and runtimes.

```bash
jupyter-mcp-server connect --help

Usage: jupyter-mcp-server connect [OPTIONS]

Connect a Jupyter MCP Server to a document and a runtime.

Options:
  --provider [jupyter|datalayer]      Provider type (default: jupyter)
  --jupyterlab BOOLEAN               Enable JupyterLab mode (default: true)
  --runtime-url TEXT                  Runtime URL for kernel operations (default: None)
  --runtime-token TEXT                Runtime authentication token (default: None)
  --runtime-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 runtime URLs (default: None)
  --jupyter-token TEXT                Jupyter token as default for both document and runtime tokens (default: None)
  --jupyter-mcp-server-url TEXT       URL of the Jupyter MCP Server to connect to (default: http://localhost:4040)
```

--------------------------------

### Start Standalone MCP Server without Authentication

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/security/index.mdx

Starts the standalone MCP server with streamable-http transport, explicitly disabling MCP client authentication. Use with caution and only in trusted network environments.

```bash
jupyter-mcp-server start \
  --transport streamable-http \
  --jupyter-token JUPYTER_SECRET \
  --insecure-mcp-noauth
```

--------------------------------

### Build Python Package or Docker Image

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/CONTRIBUTING.md

Build the Python package for distribution or create a Docker image for deployment.

```bash
# Build the Python package
make build
```

```bash
# Build the Docker image
make build-docker
```

--------------------------------

### FastMCP Server Initialization and Tool Registration

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/ARCHITECTURE.md

Initializes the global MCP server instance with CORS support and registers a file listing tool. Use this for setting up the main server logic and defining available operations.

```python
# Global MCP server instance with CORS support
mcp = FastMCPWithCORS(name="Jupyter MCP Server", json_response=False, stateless_http=True)
notebook_manager = NotebookManager()
server_context = ServerContext.get_instance()

# Tool registration and execution
@mcp.tool() async def list_files(path: str = "", max_depth: int = 1, ...) -> str:
    """List files and directories in Jupyter server filesystem"""
    return await safe_notebook_operation(
        lambda: ListFilesTool().execute(
            mode=server_context.mode,
            server_client=server_context.server_client,
            contents_manager=server_context.contents_manager,
            path=path,
            max_depth=max_depth,
            ...
        )
    )
```

--------------------------------

### Development Environment Variables

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/configuration/index.mdx

Environment variables for a development setup. Specifies the Jupyter URL and token, omitting the document ID.

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

--------------------------------

### Notebook Manager Methods

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/ARCHITECTURE.md

Provides methods for managing notebook connections and kernel lifecycle, supporting both local and remote modes. It allows adding notebooks and retrieving the current WebSocket connection in MCP_SERVER mode.

```python
class NotebookManager:
    def add_notebook(self, name, kernel, server_url="local", ...):
        """Add notebook with mode detection (local vs remote)."""
    
    def get_current_connection(self):
        """Get WebSocket connection (MCP_SERVER mode only)."""
```

--------------------------------

### OpenTelemetry Span Output Format

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/hooks/index.mdx

Example of the JSONL format for OpenTelemetry spans emitted by the Jupyter MCP Server, including span details and attributes.

```json
{
  "name": "tool_call:execute_cell",
  "context": {
    "trace_id": "0x...",
    "span_id": "0x..."
  },
  "start_time": "2025-01-15T10:30:00.000000Z",
  "end_time": "2025-01-15T10:30:02.500000Z",
  "attributes": {
    "tool.name": "execute_cell",
    "result.summary": "..."
  }
}
```

--------------------------------

### Distributed Computing Environment Variables

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/configuration/index.mdx

Environment variables for a distributed computing setup. Configures file access and compute node connections, disabling image output.

```bash
DOCUMENT_URL=http://file-server:8888
DOCUMENT_TOKEN=file-access-token
RUNTIME_URL=http://compute-node:8888
RUNTIME_TOKEN=compute-access-token
ALLOW_IMG_OUTPUT=false
```

--------------------------------

### Registering a Custom Hook Handler

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/hooks/index.mdx

Demonstrates how to obtain the singleton HookRegistry instance and register a custom handler with it.

```python
from jupyter_mcp_server.hooks import HookRegistry

registry = HookRegistry.get_instance()

```

--------------------------------

### List Notebooks Flow (JUPYTER_SERVER Mode)

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/ARCHITECTURE.md

Illustrates the request flow for listing notebooks when the server is in JUPYTER_SERVER mode with LocalBackend. This involves an HTTP POST request to the /mcp/tools/call endpoint.

```text
MCP Client
  → POST /mcp/tools/call {"tool_name": "list_notebooks"}
    → MCPSSEHandler (or MCPToolsCallHandler)
      → FastMCP calls @mcp.tool() wrapper
        → ListNotebooksTool().execute(
            mode=JUPYTER_SERVER,
            notebook_manager=notebook_manager
          )
          → notebook_manager.list_all_notebooks()
            → Returns managed notebooks from memory
          ← TSV-formatted table
        ← Tool result
      ← JSON-RPC response
    ← SSE message
  ← Tool result displayed
```

--------------------------------

### Connect via Endpoint to Existing Runtime

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/configuration/index.mdx

Connects to a Jupyter MCP Server using the 'connect' command, specifying a Datalayer provider and details for document and runtime.

```bash
jupyter-mcp-server connect \
  --provider datalayer \
  --document-url <url> \
  --document-id <document> \
  --document-token <token> \
  --runtime-url <url> \
  --runtime-id <runtime-id> \
  --runtime-token <token> \
  --jupyter-mcp-server-url http://localhost:4040
```

--------------------------------

### Enable Additional JupyterLab Tools

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/README.md

Example of enabling specific Jupyter MCP tools in JupyterLab mode via command-line arguments. This allows customization of available notebook operations and console commands.

```bash
jupyter lab --port 4040 --IdentityProvider.token MY_TOKEN --JupyterMCPServerExtensionApp.allowed_jupyter_mcp_tools="notebook_run-all-cells,notebook_get-selected-cell,notebook_append-execute,console_create"
```

--------------------------------

### Create and Push Git Version Tag

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/RELEASE.md

Use this command to create a Git tag for a new version and push it to the remote repository.

```bash
git tag v1.0.0
git push origin v1.0.0
```

--------------------------------

### Simplified Token Configuration

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/security/index.mdx

Recommended JSON configuration for setting Jupyter URL and token when document storage and runtime execution are on the same server.

```json
{
  "env": {
    "JUPYTER_URL": "http://localhost:8888",
    "JUPYTER_TOKEN": "MY_TOKEN"
  }
}
```

--------------------------------

### Advanced Jupyter Provider Configuration

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-stdio/index.mdx

This configuration separates document storage and runtime execution, useful for complex deployments. It requires separate URLs and tokens for document and runtime services. Ensure Docker is installed and the datalayer/jupyter-mcp-server image is available.

```json
{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DOCUMENT_URL",
        "-e", "DOCUMENT_TOKEN",
        "-e", "DOCUMENT_ID",
        "-e", "RUNTIME_URL",
        "-e", "RUNTIME_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "--network=host",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "DOCUMENT_URL": "http://localhost:8888",
        "DOCUMENT_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "RUNTIME_URL": "http://localhost:8888",
        "RUNTIME_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}
```

--------------------------------

### Configure User Settings for Jupyter MCP Server (Simplified)

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/clients/vscode/index.mdx

Add this JSON configuration to your user settings.json file to set up the Jupyter MCP Server for simplified deployments. Restart VS Code after applying changes.

```json
{
  "mcp": {
    "servers": {
    "DatalayerJupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "JUPYTER_URL",
        "-e",
        "JUPYTER_TOKEN",
        "-e",
        "DOCUMENT_ID",
        "-e",
        "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://host.docker.internal:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}
}
```

--------------------------------

### Configure Workspace Settings for Jupyter MCP Server (Advanced)

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/clients/vscode/index.mdx

This advanced JSON configuration for `.vscode/mcp.json` supports separate document and runtime servers. Update the values to match your specific deployment details.

```json
{
  "servers": {
    "DatalayerJupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DOCUMENT_URL",
        "-e",
        "DOCUMENT_TOKEN",
        "-e",
        "DOCUMENT_ID",
        "-e",
        "RUNTIME_URL",
        "-e",
        "RUNTIME_TOKEN",
        "-e",
        "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "DOCUMENT_URL": "http://host.docker.internal:8888",
        "DOCUMENT_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "RUNTIME_URL": "http://host.docker.internal:8888",
        "RUNTIME_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}
}
```

--------------------------------

### Single-User Dockerfile for MCP Server

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/multi-users/index.mdx

A sample Dockerfile for a single-user Jupyter environment that includes the necessary packages for Jupyter MCP Server and related tools. Ensure versions are compatible.

```dockerfile
# Dockerfile for single-user image
FROM jupyter/minimal-notebook:latest

RUN pip install "jupyter-mcp-server>=0.15.0" \
                "jupyterlab==4.4.1" \
                "jupyter-collaboration==4.0.2" \
                "ipykernel" \
                "pycrdt"
```

--------------------------------

### Enable OTel Tracing via Jupyter Extension Traitlet

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/hooks/index.mdx

Configure the OpenTelemetry output file path for the Jupyter MCP Server extension using a traitlet, either via the command line or in a configuration file.

```python
jupyter lab \
  --JupyterMCPServerExtensionApp.otel_file=/tmp/mcp_spans.jsonl \
  --port 8888 \
  --IdentityProvider.token MY_TOKEN
```

```python
c.JupyterMCPServerExtensionApp.otel_file = "/tmp/mcp_spans.jsonl"
```

--------------------------------

### Create Docker Service with Secrets

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/security/index.mdx

Use this command to create a Docker service and inject secrets like authentication tokens.

```bash
docker service create \
  --secret jupyter_token \
  datalayer/jupyter-mcp-server
```

--------------------------------

### UseNotebookTool Implementation

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/ARCHITECTURE.md

Represents a tool for connecting to or creating notebooks. This is part of the multi-notebook management suite.

```python
class UseNotebookTool(BaseTool):    # Connect/create notebooks
```

--------------------------------

### use_notebook

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/tools/index.mdx

Activates a specified notebook for subsequent cell operations, with options to connect to an existing notebook or create a new one.

```APIDOC
## use_notebook

### Description
Use a notebook and activate it for following cell operations.

### Input
- **notebook_name** (string): Unique identifier for the notebook
- **notebook_path** (string): Path to the notebook file, relative to the Jupyter server root (e.g. "notebook.ipynb")
- **mode** (string): Notebook operation mode: "connect" to connect to existing and activate it, "create" to create new and activate it (default: "connect")
- **kernel_id** (string, optional): Specific kernel ID to use (will create new if skipped)

### Returns
Success message with notebook information including activation status, kernel details, and notebook overview
```

--------------------------------

### Run Container with Least Privilege

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/security/index.mdx

Execute containers with minimal privileges to enhance security. This includes read-only filesystem, dropping all capabilities, and preventing privilege escalation.

```bash
docker run \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  datalayer/jupyter-mcp-server
```

--------------------------------

### Pack MCPB Bundle

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/mcpb/README.md

Build the .mcpb file from the current directory using the mcpb pack command. This command generates the distributable bundle.

```bash
cd mcpb
mcpb pack
```

--------------------------------

### list_notebooks

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/reference/tools/index.mdx

Lists all notebooks that have been previously used with the `use_notebook` tool, showing their status and activation.

```APIDOC
## list_notebooks

### Description
List all notebooks that have been used via use_notebook tool.

### Input
None

### Returns
TSV formatted table with notebook information
- **Name**: Unique identifier for the notebook
- **Path**: Path to the notebook file
- **Kernel_ID**: Kernel ID associated with the notebook
- **Kernel_Status**: Current status of the kernel
- **Activate**: "✓" if this is the currently active notebook, empty otherwise
```

--------------------------------

### Advanced Jupyter MCP Server Configuration using Docker (MacOS/Windows)

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyter-stdio/index.mdx

Provides an advanced Docker configuration for MacOS and Windows, separating document storage and runtime execution. It maps environment variables for document and runtime URLs, tokens, and document ID.

```json
{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DOCUMENT_URL",
        "-e", "DOCUMENT_TOKEN",
        "-e", "DOCUMENT_ID",
        "-e", "RUNTIME_URL",
        "-e", "RUNTIME_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "DOCUMENT_URL": "http://host.docker.internal:8888",
        "DOCUMENT_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "RUNTIME_URL": "http://host.docker.internal:8888",
        "RUNTIME_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}
```

--------------------------------

### MCP Client Configuration

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/CONTRIBUTING.md

Configuration file for the MCP client, specifying the server command, arguments, and environment variables.

```json
{
    "mcpServers": {
        "Jupyter-MCP": {
            "command": "uvx",
            "args": [
                "--from",
                "your/path/to/jupyter-mcp-server/dist/jupyter_mcp_server-x.x.x-py3-none-any.whl",
                "jupyter-mcp-server"
            ],
            "env": {
                "JUPYTER_URL": "http://localhost:8888",
                "JUPYTER_TOKEN": "MY_TOKEN",
                "ALLOW_IMG_OUTPUT": "true"
            }
        }
    }
}
```

--------------------------------

### RestartNotebookTool Implementation

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/ARCHITECTURE.md

Represents a tool for restarting kernels associated with notebooks. This is part of the multi-notebook management suite.

```python
class RestartNotebookTool(BaseTool): # Restart kernels
```

--------------------------------

### Local Testing URL Format

Source: https://github.com/datalayer/jupyter-mcp-server/blob/main/docs/docs/providers/jupyterhub-streamable-http/index.mdx

Use this simpler URL format for single-user deployments or local testing of the MCP endpoint.

```text
http://localhost:8000/user/<username>/mcp
```