What can you do with this server?

Manage JupyterLab compute sessions on SLURM/local, execute and edit notebook code, and shut down sessions. * Start new sessions (submits SLURM job, starts kernel, creates notebook). * Resume existing notebooks by re-executing all cells to restore kernel state. * Continue notebooks by forking with a fresh kernel without re-execution. * Execute arbitrary Python code in a session's kernel and append it as a notebook cell. * Edit existing cells and re-execute them, supporting negative cell indices. * Add markdown cells to notebooks. * Shut down sessions, stopping the kernel and canceling the SLURM job.

Which integrations are available for this server?

Enables the execution of Python code on GPU compute nodes by managing JupyterLab instances and IPython kernels within a SLURM-managed environment. Allows for the addition of Markdown cells to notebooks to provide documentation and structure alongside executed code. Provides tools for executing Python code, managing session kernels, and manipulating notebook cells on high-performance compute clusters. Supports GPU-accelerated computing workloads by facilitating the use of PyTorch on compute nodes allocated via job schedulers.

How do I use jlab-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@jlab-mcp Train a PyTorch model on a GPU node and display the training loss" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

jlab-mcp

by kdkyum

Overview Schema Source Related Servers Discussions Admin

Python

Remote

jlab-mcp

A Model Context Protocol (MCP) server that enables Claude Code to execute Python code on GPU compute nodes via JupyterLab running on a SLURM cluster.

Inspired by and adapted from goodfire-ai/scribe, which provides notebook-based code execution for Claude. This project adapts that approach for HPC/SLURM environments where GPU resources are allocated via job schedulers.

Architecture

Claude Code
    ↕ stdio
MCP Server
    ↕ HTTP/WebSocket
JupyterLab (SLURM compute node or local subprocess)   ← one server, many kernels
    ↕
IPython Kernels (GPU access)

JupyterLab runs either on a SLURM compute node (HPC clusters) or as a local subprocess (laptops/workstations). The server process is decoupled from the MCP server and keeps running across Claude Code sessions. It can be started two ways:

From Claude (recommended): the agent calls the start_server MCP tool, which asks you once whether to run on SLURM or locally (and, for SLURM, the job walltime and resources), launches jlab-mcp start in the background (bootstrapping a bare project with uv init/uv add if needed), then monitors startup with wait_for_server and tells you when it's ready.
Manually: run jlab-mcp start in a separate terminal.

All sessions create separate kernels on this shared server. Each project directory gets its own JupyterLab instance — the status file is scoped by a hash of the working directory where the server was started.

Related MCP server: Jupyter MCP Server

Local Mode

On machines without SLURM (laptops, workstations), jlab-mcp runs JupyterLab as a local subprocess.

How the mode is chosen:

Via the start_server MCP tool: on first use in a project it asks you (slurm or local) and saves the choice next to the project's status file (~/.jlab-mcp/servers/{name}-{hash}/run-mode). Pass mode explicitly to change it later.
Via the CLI (jlab-mcp start): auto-detected — if sbatch is on PATH, SLURM mode; otherwise local mode.
The JLAB_MCP_RUN_MODE environment variable overrides both:

export JLAB_MCP_RUN_MODE=local   # force local mode
export JLAB_MCP_RUN_MODE=slurm   # force SLURM mode

In local mode, jlab-mcp start runs in the foreground — press Ctrl+C to stop. The status file uses the same format as SLURM mode, so the MCP server works identically in both modes.

Setup

Zero-install (recommended)

The only prerequisites are Claude Code and uv. Drop this .mcp.json into any project directory — uvx fetches and runs jlab-mcp on demand (cached after the first run), no separate install step:

{
  "mcpServers": {
    "jlab-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kdkyum/jlab-mcp.git", "jlab-mcp"]
    }
  }
}

Start Claude Code in that directory and approve the MCP server when prompted. The first launch clones and builds the package, so it can take a little longer; pin a tag (git+...@v1.0.2) for reproducibility.

Pre-installed alternative

For faster MCP startup (or offline login nodes), install the CLI once and reference it directly:

uv tool install git+https://github.com/kdkyum/jlab-mcp.git

The SLURM job activates .venv in the current working directory. If the project has no environment yet (e.g. a fresh directory with just .mcp.json), start_server bootstraps it automatically (uv init --bare + uv add jupyterlab ipykernel matplotlib numpy). To set it up manually, or to add GPU-enabled torch:

cd /shared/fs/my-project
uv venv
uv pip install jupyterlab ipykernel matplotlib numpy
uv pip install torch --index-url https://download.pytorch.org/whl/cu126   # NVIDIA GPUs
# AMD GPUs (e.g. MI300A): use the ROCm wheels instead
# uv pip install torch --index-url https://download.pytorch.org/whl/rocm6.3

Usage

Option A: Let Claude manage the server

Just start Claude Code in your project directory and ask it to run something in a notebook. When no server is running, the agent calls start_server (asking you SLURM vs local on first use), waits in the background via wait_for_server, and reports when JupyterLab is ready. To stop the server, ask Claude or run jlab-mcp stop.

Option B: Manual CLI

1. Start the compute node

In a separate terminal, start the SLURM job:

jlab-mcp start              # uses default time limit (4h)
jlab-mcp start 24:00:00     # 24 hour time limit
jlab-mcp start 1-00:00:00   # 1 day

This submits the job and waits until JupyterLab is ready:

SLURM job 24215408 submitted, waiting in queue...
Job running on ravg1011, JupyterLab starting...
JupyterLab ready at http://ravg1011:18432

2. Use Claude Code

In another terminal, start Claude Code. The MCP server connects to the running JupyterLab automatically.

3. Stop when done

jlab-mcp stop

CLI Commands

Command	Description
`jlab-mcp start [TIME] [--debug]`	Start JupyterLab and wait until ready. In SLURM mode, submits a job and polls until the server responds. In local mode, spawns a subprocess and blocks in the foreground. Optional TIME overrides `JLAB_MCP_SLURM_TIME` (e.g. `24:00:00`). Skips submission if an existing server is still running.
`jlab-mcp stop`	Stop JupyterLab. In SLURM mode, runs `scancel`. In local mode, sends SIGTERM to the subprocess. Removes the status file in both cases.
`jlab-mcp wait`	Poll the status file from another terminal until the server is ready (up to 10 min). Prints state transitions (`pending → starting → ready`). Useful for scripts or for monitoring `start` progress from a separate shell.
`jlab-mcp status`	Print server state, mode, hostname, port, and whether the process/job is alive. Lists active kernels with execution state and last activity time. Queries GPU memory and utilization via `nvidia-smi` on a temporary kernel.
`jlab-mcp`	Run MCP server (stdio transport, used by Claude Code — not run manually)

All commands accept --debug to enable verbose logging (status file reads, SLURM parameters, health check attempts, connection file paths) on stderr.

The SLURM job survives Claude Code restarts. You only need to run jlab-mcp start once per work session.

Configuration

All settings are configurable via environment variables. No values are hardcoded for a specific cluster.

Environment Variable	Default	Description
`JLAB_MCP_DIR`	`~/.jlab-mcp`	Base working directory
`JLAB_MCP_NOTEBOOK_DIR`	`./notebooks`	Notebook storage (relative to cwd)
`JLAB_MCP_SERVER_ROOT_DIR`	cwd	JupyterLab root directory (what the file browser sees)
`JLAB_MCP_LOG_DIR`	`~/.jlab-mcp/logs`	SLURM job logs
`JLAB_MCP_STATUS_DIR`	`~/.jlab-mcp/servers/{name}-{hash}`	Per-project status directory (auto-derived from cwd)
`JLAB_MCP_CONNECTION_DIR`	`~/.jlab-mcp/connections`	Connection info files
`JLAB_MCP_SLURM_PARTITION`	`gpu`	SLURM partition
`JLAB_MCP_SLURM_GRES`	`gpu:1`	SLURM generic resource
`JLAB_MCP_SLURM_CPUS`	`4`	CPUs per task
`JLAB_MCP_SLURM_MEM`	`32000`	Memory in MB
`JLAB_MCP_SLURM_TIME`	`4:00:00`	Wall clock time limit
`JLAB_MCP_SLURM_BIND_IP`	`0.0.0.0`	Address JupyterLab binds to on the compute node. Default listens on all interfaces and advertises the node's `$(hostname)`; a concrete IP binds that one interface and advertises that exact IP
`JLAB_MCP_SLURM_MODULES`	(empty)	Space-separated modules to load (e.g. `cuda/12.6`)
`JLAB_MCP_QUEUE_TIMEOUT`	`300`	Seconds `start` waits for the job to leave the queue. On timeout the job stays queued — rerun `jlab-mcp start` to resume waiting
`JLAB_MCP_READY_TIMEOUT`	`120`	Seconds to wait for JupyterLab once the job is running. On timeout the job is cancelled
`JLAB_MCP_WALLTIME_WARN_SECONDS`	`3600`	Remaining SLURM walltime below which `ping`/`start_server` include a save-your-work warning
`JLAB_MCP_PORT_MIN`	`18000`	Port range lower bound
`JLAB_MCP_PORT_MAX`	`19000`	Port range upper bound
`JLAB_MCP_RUN_MODE`	(auto)	`local` or `slurm` (auto-detects based on `sbatch` availability)
`JLAB_MCP_LOCAL_BIND_IP`	`0.0.0.0`	Address JupyterLab binds to in local mode. Default listens on all interfaces (UI reachable from other hosts / a container host); the same-host MCP server still connects over loopback. Set `127.0.0.1` to restrict JupyterLab to loopback only

Example: Cluster with A100 GPUs and CUDA module

export JLAB_MCP_SLURM_PARTITION=gpu1
export JLAB_MCP_SLURM_GRES=gpu:a100:1
export JLAB_MCP_SLURM_CPUS=18
export JLAB_MCP_SLURM_MEM=125000
export JLAB_MCP_SLURM_TIME=1-00:00:00
export JLAB_MCP_SLURM_MODULES="cuda/12.6"

Claude Code Integration

Use the zero-install .mcp.json from Setup, or — with the CLI pre-installed — reference the binary directly in ~/.claude.json or a project .mcp.json:

{
  "mcpServers": {
    "jlab-mcp": {
      "command": "jlab-mcp"
    }
  }
}

No env block is needed: on first use the agent surveys the cluster (sinfo) and asks you for walltime and resources, saving the choices per project. An env block with JLAB_MCP_* variables still works to pin cluster-specific defaults (e.g. JLAB_MCP_SLURM_MODULES for a CUDA module).

The MCP server uses the working directory to find .venv for the compute node. Claude Code launches from your project directory, so it picks up the right venv automatically.

MCP tools

Tool	Description
`start_server`	Launch JupyterLab in the background through `jlab-mcp start`. Saves the selected local or SLURM mode and resource options per project
`wait_for_server`	Monitor server startup with MCP progress notifications
`create_notebook`	Create an empty notebook without starting a kernel; existing filenames receive a numeric suffix
`open_notebook`	Read a document without a kernel; optional `include_cells="summary"` or `"source"`
`start_new_notebook`	Create a notebook and its kernel, preserving every existing kernel
`start_notebook`	Attach to a notebook and report `kernel_reused`, `kernel_created`, kernel status, and cell count. Source requires `include_cells="source"`
`list_cells`	List code and Markdown cells with stable `cell_id`, index, `source_hash`, and output counts
`get_cell`	Read one cell by ID or index, with optional source and execution history
`add_code_cell`	Insert source without executing code or advancing the kernel execution count
`edit_cell`	Edit code without execution. Changed source clears current outputs; identical source preserves them
`add_markdown`, `edit_markdown`	Insert or edit Markdown without execution
`delete_cell`	Delete a cell by stable ID or index
`batch_edit`	Validate insert, edit, delete, and move operations before applying them in one notebook save
`start_run`	Start a background run and return a durable run ID. Supports cell ranges, explicit cell IDs, and idempotent `request_id` retries
`get_run_status`	Query started and completed cells, elapsed times, latest text, errors, and capture/save status
`get_run_output`	Retrieve captured output while a cell runs or after it finishes, including results for old source revisions
`cancel_run`	Explicitly interrupt a run without shutting down its kernel
`execute_code`	Insert and execute a cell in the foreground, with durable run history
`run_cell`, `run_cells`	Execute existing source in the foreground with the same run records and kernel reservations
`get_cell_output`	Read saved notebook output with optional output selection, image previews, original images, and metadata
`execute_scratch`	Execute diagnostic code on a temporary kernel without a notebook
`interrupt_kernel`	Send an interrupt to a session's kernel
`shutdown_session`	Explicitly stop one kernel; other kernels and the JupyterLab server remain available
`ping`	Check server reachability, list kernels and notebook associations, and report SLURM walltime
`check_resources`	Inspect CPU, memory, and GPU usage through a temporary kernel

Resource: jlab-mcp://server/status returns server information and active sessions.

Background runs

start_run snapshots the selected cell IDs and exact source before execution. Index ranges are inclusive; cell_ids executes IDs in the supplied order. Markdown is skipped. A second execution request on the same kernel returns state="busy" and active_run_id. This reservation covers the whole run, including foreground execution tools. It does not control requests sent directly from JupyterLab or other kernel clients.

run = start_run(session_id="SESSION", request_id="training-attempt-1")
get_run_status(run_id=run["run_id"], include_cells=True)
get_run_output(run_id=run["run_id"], cell_id="CELL")

A retry with the same request_id and execution parameters returns the existing run, even if its source has since changed. Reusing that identifier with different parameters returns a conflict. Request identifiers are unique within the project's run store. No automatic history expiration is applied.

State	Meaning
`queued`	The run is recorded and its worker is starting
`running`	The worker is dispatching or monitoring cells
`cancelling`	Cancellation was requested; the worker is waiting for execution to finish
`completed`	Every selected cell completed without a reported execution error
`failed`	One or more cells failed; `error_kind` distinguishes Python exceptions from failures before delivery. `stop_on_error` controls whether later cells run
`cancelled`	The run was cancelled, with no remaining cells dispatched
`kernel_died`	Kernel death, restart, or removal was detected
`unknown`	Execution outcome cannot be established; the kernel remains reserved

started_code_cells counts cells acknowledged by the kernel. completed_code_cells counts cells whose execution reached the matching idle message, including cells that raised a Python exception. Neither count estimates training steps or loop iterations. current_cell.index is the index at the time of the source snapshot.

Status and output queries do not control execution. Cancelling a query or allowing it to time out leaves the run alone. cancel_run requests an interrupt; an unconfirmed interrupt remains uncertain. A foreground execution call retains its cancellation behavior and requests cancellation of its run. Per-cell timeout limits monitoring, not kernel computation; an expired timeout produces unknown and requires explicit cancellation before another run can use that kernel.

Durable capture and recovery

The project stores run records, source snapshots, received outputs, and session mappings in STATUS_DIR/runs/runs.sqlite3. SQLite commits captured outputs with synchronous=FULL. Image originals are retained. get_run_status reports notebook attachment through outputs_saved and durable capture through captured_outputs_saved; per-cell details distinguish notebook_saved, capture_saved, output_capture_complete, save_error, and capture_error.

Background workers live in the MCP process. They continue after a start response and across client reconnections while that process stays alive. If the MCP process exits, the kernel may continue the current cell, but the remaining cells are not dispatched. A new MCP process recovers the saved run and session mappings. Unfinished runs become unknown and are never restarted automatically. Captured messages remain retrievable; messages not received and committed before the crash cannot be promised recoverable.

A WebSocket reconnect listens for the existing request without resending code. Any connection gap marks output capture incomplete. Python exceptions, connection failures, and kernel death have separate status fields. An idle kernel after a disconnect does not establish whether a request finished or never arrived.

Source revisions and document edits

Editing and reading tools accept either session_id or notebook_path. Paths stay within JLAB_MCP_NOTEBOOK_DIR. create_notebook and open_notebook need no JupyterLab server. Cell edits, deletion, execution, and output retrieval accept stable cell IDs; integer indices remain available. expected_source_hash on edits and deletion returns a conflict with the current source instead of overwriting a changed cell. batch_edit supports the same check per operation and leaves the document unchanged if validation fails.

Each execution records its run ID, cell ID, exact source hash, execution count, and timestamps. Before saving results as current notebook output, the writer compares that hash with the cell's current source. Moving a cell preserves its output association. Editing its source during execution leaves the old result in run history and reports source_mismatch; it does not attach that result to the new source. get_run_output(include_source=true) retrieves the executed source alongside its result.

Identical-source edits preserve the file and outputs. Changed source clears current outputs. Earlier tool executions remain available by run ID. edit_cell(preserve_history=true) also copies the previous outputs and source into cell metadata, including outputs that predate run tracking; get_cell(include_history=true) reads that history.

Notebook writes use a lock shared by all managers for the same file within one MCP process. Revision checks compare the version read by the tool. They cannot lock out a separate JupyterLab process writing the file at the same instant.

Output and figure selection

Both output tools return a JSON metadata block followed by the selected content. metadata_only=true returns counts, output types, image dimensions, and execution provenance. output_index selects one output; start_output and end_output select an inclusive range. Negative indices count from the end. Indices refer to the output entries reported by that tool's metadata, not just images.

get_cell_output(session_id="SESSION", cell_id="CELL", metadata_only=True)
get_cell_output(
	session_id="SESSION", cell_id="CELL", output_index=4,
	include_images=True, image_resolution="original",
)

Images are omitted by default. image_resolution="preview" caps the longest dimension at max_image_dimension, default 2576. "original" returns the original captured image. Preview settings never alter saved output. max_chars limits returned text to its tail; zero disables truncation.

Kernel lifecycle

Creating notebook B preserves notebook A's kernel and variables. Opening a notebook reports whether it reused a recorded live kernel or created a fresh one. A failed liveness check leaves the existing session intact and does not create a replacement. Session mappings persist across MCP restarts. shutdown_session followed by start_notebook starts a fresh kernel for the same document.

Testing

# Unit tests (no SLURM needed)
uv run python -m pytest tests/ --ignore=tests/test_tools.py -v

# Isolated local integration tests, using a disposable JupyterLab server
JLAB_MCP_TEST_LOCAL=1 uv run python -m pytest tests/test_live_runs.py tests/test_tools.py -v --timeout=120

# Existing-server integration tests, after running `jlab-mcp start`
uv run python -m pytest tests/test_tools.py -v -s --timeout=600

Acknowledgments

This project is inspired by goodfire-ai/scribe, which provides MCP-based notebook code execution for Claude. The tool interface design, image resizing approach, and notebook management patterns are adapted from scribe for use on HPC/SLURM clusters.

License

MIT

Available Tools

7 tools

add_markdownB

Add a markdown cell to the notebook.

Args: session_id: Session identifier. markdown: Markdown content.

Returns: Confirmation with cell index.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes
`markdown`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states this adds a cell and returns a confirmation with cell index, which is basic. However, it doesn't cover important behavioral aspects: whether this requires specific permissions, if it modifies notebook state permanently, what happens on errors, or if there are rate limits. For a mutation tool with zero annotation coverage, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and well-structured: a clear purpose statement followed by separate 'Args' and 'Returns' sections. Every sentence earns its place by providing essential information without redundancy. The formatting with bullet-like sections enhances readability while maintaining brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (adding content to a notebook), no annotations, and an output schema that presumably covers the return value, the description is minimally adequate. It explains what the tool does and documents parameters, but lacks behavioral context like error handling or side effects. The presence of an output schema means the description doesn't need to detail return values, but other gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explicitly documents both parameters ('session_id' and 'markdown') with brief explanations, adding meaningful context beyond the schema's 0% description coverage. It clarifies that 'session_id' identifies the session and 'markdown' is the content, which compensates well for the schema's lack of descriptions. With only 2 parameters, this provides adequate semantic information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Add') and resource ('markdown cell to the notebook'), making the purpose immediately understandable. It distinguishes this from siblings like 'edit_cell' or 'execute_code' by specifying it's for adding markdown content rather than editing existing cells or running code. However, it doesn't explicitly contrast with 'start_new_session' or other session management tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'edit_cell' for modifying existing cells or 'execute_code' for code cells. It doesn't mention prerequisites such as needing an active session (implied by session_id but not stated) or when markdown cells are appropriate versus other cell types.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_cellC

Edit an existing cell, re-execute it, and update outputs.

Args: session_id: Session identifier. cell_index: Cell index (supports negative indexing). code: New code for the cell.

Returns: Formatted output string.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes
`cell_index`	Yes
`code`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but provides minimal behavioral context. It mentions that editing triggers re-execution and output updates, but doesn't cover important aspects like error handling, permission requirements, whether changes are reversible, or side effects on other cells/sessions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the core functionality. The Args/Returns sections are structured but could be more integrated. Every sentence adds value, though the formatting is slightly verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters with 0% schema coverage and no annotations, the description provides basic parameter semantics and mentions the return format. However, for a mutation tool that edits and executes code, it lacks sufficient context about behavioral implications, error conditions, and integration with sibling tools. The output schema exists, reducing the need to explain return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides basic semantic meaning for all three parameters (session_id as identifier, cell_index with negative indexing support, code as new content), but lacks details about format constraints, valid ranges, or examples. This meets the baseline for 0% coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('edit', 're-execute', 'update') and identifies the resource ('existing cell'). It distinguishes this from siblings like 'add_markdown' (creation) and 'execute_code' (execution only), but doesn't explicitly contrast with all siblings like session management tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus alternatives. The description doesn't mention prerequisites (e.g., needing an active session), exclusions, or comparisons to similar tools like 'execute_code' for execution without editing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

execute_codeB

Execute code in the kernel and add cell to notebook.

Args: session_id: Session identifier. code: Python code to execute.

Returns: Formatted output string.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes
`code`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but offers minimal behavioral context. It mentions that execution occurs 'in the kernel' and 'add[s] cell to notebook,' but lacks details on permissions, error handling, rate limits, or whether this is a read-only or destructive operation. The phrase 'Execute code' implies mutation, but this isn't explicitly confirmed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with the core purpose stated first, followed by parameter and return explanations. However, the 'Args:' and 'Returns:' sections could be integrated more smoothly, and some redundancy exists (e.g., 'Execute code' and 'code: Python code to execute').

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (code execution in a kernel), no annotations, and an output schema present (which covers return values), the description is moderately complete. It explains parameters and returns but lacks crucial context like session prerequisites, safety warnings, or differentiation from siblings, leaving gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining both parameters: 'session_id: Session identifier' and 'code: Python code to execute.' This adds clear meaning beyond the bare schema, though it doesn't specify formats or constraints (e.g., session_id format, code limitations).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Execute code in the kernel and add cell to notebook.' This specifies the verb ('Execute'), resource ('code'), and context ('kernel', 'notebook'), though it doesn't explicitly differentiate from siblings like 'edit_cell' or 'start_session_continue_notebook'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites like needing an active session, nor does it clarify distinctions from sibling tools such as 'edit_cell' (which might modify existing cells) or session management tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

shutdown_sessionA

Shutdown session: stop kernel and cancel SLURM job.

Args: session_id: Session identifier.

Returns: Confirmation message.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses key behavioral traits: it's a destructive operation (shutdown/stop/cancel) and mentions both kernel and SLURM job termination. However, it doesn't address permissions needed, whether changes are reversible, or error conditions, leaving gaps in behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear purpose statement followed by separate Args and Returns sections. Every sentence earns its place by providing necessary information without redundancy, making it easy to parse and understand.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (destructive operation), no annotations, and an output schema (which handles return values), the description is reasonably complete. It covers purpose, parameter meaning, and return confirmation, though could benefit from more behavioral details like prerequisites or side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and only 1 parameter, the description adds essential meaning by explaining 'session_id' as a 'Session identifier', which clarifies what the parameter represents beyond just its name. This compensates well for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('shutdown', 'stop', 'cancel') and resources ('session', 'kernel', 'SLURM job'), distinguishing it from sibling tools like start_new_session which have opposite functions. It precisely communicates the tool's destructive termination action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying it's for shutting down sessions, suggesting it should be used when a session is no longer needed versus starting tools. However, it doesn't explicitly state when-not to use it or name specific alternatives, missing full explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_new_sessionA

Start a new session: submit SLURM job, start kernel, create notebook.

Args: experiment_name: Name for the experiment/notebook.

Returns: Dict with session_id, notebook_path, job_id, hostname.

ParametersJSON Schema

Name	Required	Description	Default
`experiment_name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the actions (submit job, start kernel, create notebook) but omits details like required permissions, potential side effects (e.g., resource allocation), or error handling. It adds some context but falls short of fully describing behavioral traits for a tool that initiates processes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by structured sections for Args and Returns. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (initiates multiple operations) and no annotations, the description does well by outlining actions, parameters, and return values. The presence of an output schema reduces the need to detail returns, but it could benefit from more behavioral context, such as execution time or failure modes, to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description must compensate. It provides the parameter 'experiment_name' with a clear meaning ('Name for the experiment/notebook'), adding essential semantics beyond the schema. However, it doesn't specify constraints like length or allowed characters, leaving some gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Start a new session') and enumerates the three concrete operations it performs: 'submit SLURM job, start kernel, create notebook.' It distinguishes itself from sibling tools like 'shutdown_session' or 'start_session_continue_notebook' by emphasizing it's for initiating a new session from scratch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying it's for starting a 'new session,' which differentiates it from siblings like 'start_session_continue_notebook' or 'start_session_resume_notebook' that handle existing sessions. However, it lacks explicit guidance on when not to use it or detailed prerequisites, such as whether prior setup is needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_session_continue_notebookA

Continue a notebook: fork it with fresh kernel (no re-execution).

Args: experiment_name: Name for this session. notebook_path: Path to existing notebook to fork.

Returns: Dict with session_id, notebook_path (forked), job_id, hostname.

ParametersJSON Schema

Name	Required	Description	Default
`experiment_name`	Yes
`notebook_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes key behaviors: forking a notebook, using a fresh kernel, and not re-executing code. However, it lacks details about permissions, rate limits, session lifecycle, or error conditions. For a session management tool with zero annotation coverage, this is a moderate gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly structured and concise: a one-sentence purpose statement followed by clearly labeled Args and Returns sections. Every sentence earns its place with no wasted words, and key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (session management with forking), no annotations, and an output schema that documents return values, the description is reasonably complete. It covers purpose, parameters, and return structure, though additional behavioral context (like auth or error handling) would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides clear semantic explanations for both parameters: 'experiment_name: Name for this session' and 'notebook_path: Path to existing notebook to fork'. This adds meaningful context beyond the bare schema types, though it doesn't cover format details or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('continue a notebook', 'fork it with fresh kernel') and distinguishes it from sibling tools like 'start_new_session' and 'start_session_resume_notebook' by specifying 'no re-execution'. It precisely identifies the resource (notebook) and action (forking with fresh kernel).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides usage guidance by stating 'continue a notebook: fork it with fresh kernel (no re-execution)', which clearly differentiates it from alternatives like 'start_session_resume_notebook' (which likely resumes with execution) and 'start_new_session' (which doesn't fork an existing notebook). It tells the agent exactly when to use this tool versus its siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_session_resume_notebookA

Resume a notebook: re-execute all cells to restore kernel state.

Args: experiment_name: Name for this session. notebook_path: Path to existing notebook to resume.

Returns: Dict with session_id, notebook_path, job_id, hostname, errors.

ParametersJSON Schema

Name	Required	Description	Default
`experiment_name`	Yes
`notebook_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool performs re-execution of all cells to restore kernel state, which implies mutation and computational effects. However, it doesn't mention permissions, rate limits, or error handling details, leaving gaps for a tool with significant behavioral impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (resuming sessions with re-execution), no annotations, and an output schema that documents return values, the description is mostly complete. It covers purpose, parameters, and returns, but could benefit from more behavioral context like prerequisites or side effects to fully guide usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful semantics beyond the input schema, which has 0% coverage. It explains that 'experiment_name' is for naming the session and 'notebook_path' is the path to an existing notebook to resume, clarifying their roles. Since there are only 2 parameters and the description covers both adequately, it compensates well for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('resume a notebook: re-execute all cells to restore kernel state'), identifies the resource (notebook), and distinguishes it from sibling tools like 'start_new_session' and 'start_session_continue_notebook' by emphasizing re-execution for restoration.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying 'resume a notebook' and 'existing notebook to resume', suggesting it's for restarting prior sessions rather than creating new ones. However, it lacks explicit guidance on when to use alternatives like 'start_new_session' or 'start_session_continue_notebook'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

7 tool updatesv0.1.0Feb 8, 2026
- First observedadd_markdown
- First observededit_cell
- First observedexecute_code
- First observedshutdown_session
- First observedstart_new_session
- First observedstart_session_continue_notebook
- First observedstart_session_resume_notebook

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored 2026-04-18 06:15 across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: adding markdown, editing cells, executing code, and managing sessions (shutdown, start new, continue, resume). There is no overlap in functionality that would cause confusion.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with snake_case (e.g., add_markdown, edit_cell, execute_code). The naming is predictable and readable throughout the set.

Tool Count5/5

With 7 tools, this server is well-scoped for Jupyter notebook management. It covers core operations (session lifecycle, code execution, cell editing) without being overly sparse or bloated.

Completeness4/5

The toolset provides comprehensive coverage for notebook operations, including session management and cell manipulation. A minor gap is the lack of a tool to delete cells or manage notebook files beyond forking/resuming, but agents can work around this.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
llm-orchestration-agent-2
ai.getvda
MCP-Native LLM Orchestration Agent
Agent Orchestration AI & Machine Learning
1
mcp-aichatOAuth
io.github.AceDataCloud
MCP server for AI dialogue using various LLM models via AceDataCloud
AI & Machine Learning
2
Remote MCP A
com.remote-mcp.mcp
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
Developer Tools Search Agent Orchestration
13

Related MCP Servers

HPC-MCP
TomMelt
A
license
B
quality
D
maintenance
A server that provides Model Control Protocol (MCP) tools for High Performance Computing, designed to integrate with Large Language Models in IDEs like Cursor and VSCode for debugging and other HPC tasks.
Updated a year ago (2025-09-26 13:58 UTC)
1
3
MIT
Jupyter MCP Server
Code Execution Data Platforms Data Visualization
ChengJiale150
A
license
A
quality
D
maintenance
AI-powered MCP server for connecting and managing Jupyter Notebooks. Enables interactive code execution, multi-notebook management, and multimodal output for data analysis, visualization, and machine learning.
Updated a year ago (2025-11-01 05:47 UTC)
12
9
MIT
globus-mcpofficial
Cloud Platforms Data Platforms Code Execution
globus
A
license
A
quality
C
maintenance
MCP server enabling LLMs to manage Globus data transfers and compute tasks.
Updated a year ago (2025-10-23 19:09 UTC)
10
11
Apache 2.0
clausius
Monitoring Observability Command Line
tamohannes
F
license
Not graded
quality
A
maintenance
An MCP server for monitoring and managing multi-cluster Slurm GPU jobs, enabling AI agents to execute commands, check allocations, and explore logs across HPC clusters.
Updated 2 months ago (2026-07-30 00:35 UTC)
1
-

jlab-mcp

Architecture

Local Mode

Setup

Zero-install (recommended)

Pre-installed alternative

Usage

Option A: Let Claude manage the server

Option B: Manual CLI

1. Start the compute node

2. Use Claude Code

3. Stop when done

CLI Commands

Configuration

Example: Cluster with A100 GPUs and CUDA module

Claude Code Integration

MCP tools

Background runs

Durable capture and recovery

Source revisions and document edits

Output and figure selection

Kernel lifecycle

Testing

Acknowledgments

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

globus-mcpofficial