Notebook execution over MCP

Reference

The operations that let the agent start a notebook server where the work needs to be, run a notebook in it with no JupyterLab tab open, and stop it when the GPU should go back to serving models.

TL;DR

Ask your agent Code to start a notebook server and run a notebook. No browser tab is needed. This page lists every operation and its limits.

How it works

Thinkube Control forwards the notebook operations to tk-notebook-mcp, a server extension inside the notebook server. The extension works on the notebook’s shared document, the same one a JupyterLab tab edits. When no tab has created the document, the extension creates it. An edit or an output written by the agent appears in any tab that has the notebook open, and the document’s autosave writes it to the file. A kernel is held by one call at a time. A second call for the same kernel waits five seconds and then answers with what holds it.

The server operations go to JupyterHub itself, with the service token Thinkube Control is registered with.

The server

A notebook runs in one server pod on one node, with the CPU, memory and GPUs chosen when JupyterHub starts it. These operations make that choice.

Operation What it does

Operation	What it does
`jupyter_notebook_status`	Whether a server is running, on which node and with how many cores, GB and GPUs, whether its tools answer, and which servers unattended runs hold.
`start_notebook_server`	Starts the server on `node` with `cpu_cores`, `memory_gb` and `gpus`, and waits until its tools answer. Values you leave out come from JupyterHub Config. The ask is checked against the node: its cores and memory, its GPUs, and the GPU slots not held by a served model. On a shared GPU such as the GB10, you can ask for one GPU at most. A server already running must be stopped first.
`stop_notebook_server`	Stops the server and frees its node, memory and GPUs. Kernels are shut down; notebook files keep their outputs.

jupyter_notebook_status

Whether a server is running, on which node and with how many cores, GB and GPUs, whether its tools answer, and which servers unattended runs hold.

start_notebook_server

Starts the server on node with cpu_cores, memory_gb and gpus, and waits until its tools answer. Values you leave out come from JupyterHub Config. The ask is checked against the node: its cores and memory, its GPUs, and the GPU slots not held by a served model. On a shared GPU such as the GB10, you can ask for one GPU at most. A server already running must be stopped first.

stop_notebook_server

Stops the server and frees its node, memory and GPUs. Kernels are shut down; notebook files keep their outputs.

A refusal says why in one sentence, for example tkspark has 0 GPU slots free of 4; a served model may be holding the rest (unload_llm_model frees one).

To use a GPU on another node, start an unattended run there, or stop the server and start it on that node.

JupyterHub stops a server whose kernels have been idle for an hour. A running cell counts as activity; an open tab or an opened notebook with an idle kernel does not. jupyter_notebook_status says whether a server is there before a tab is opened on it.

Notebooks

Paths are relative to the notebooks folder, for example examples/research-assistant/00-platform-validation.ipynb. Every operation answers with the tool’s own result: an object with success and, on failure, error in plain words.

Operation What it does

Operation	What it does
`jupyter_use_notebook`	Opens a notebook for work: starts its kernel and its shared document. Call it before running or editing cells. `kernel_name` picks the environment (`agent-dev`, `fine-tuning`); without it the kernel the notebook names is used. `create` makes the file when it does not exist; `needs_gpu` refuses when the server was started without one. The answer carries the notebook’s address and `open_in_ide`, the command that shows it in a Thinkube IDE tab.
`jupyter_close_notebook`	Saves the document and shuts the kernel down, freeing the memory it held.
`jupyter_list_notebooks`	Every notebook under the notebooks folder, with the kernel each open one uses.
`jupyter_create_notebook`	Creates a notebook file, with optional initial cells.
`jupyter_list_cells`, `jupyter_read_cell`	The cells by index with type, execution count and first line; one cell’s full source and outputs.
`jupyter_insert_cell`, `jupyter_overwrite_cell`, `jupyter_delete_cell`, `jupyter_move_cell`	Edits. `insert_cell` takes `position`: `end`, or `above` or `below` a `cell_index`. Overwrite and delete return the previous source.

jupyter_use_notebook

Opens a notebook for work: starts its kernel and its shared document. Call it before running or editing cells. kernel_name picks the environment (agent-dev, fine-tuning); without it the kernel the notebook names is used. create makes the file when it does not exist; needs_gpu refuses when the server was started without one. The answer carries the notebook’s address and open_in_ide, the command that shows it in a Thinkube IDE tab.

jupyter_close_notebook

Saves the document and shuts the kernel down, freeing the memory it held.

jupyter_list_notebooks

Every notebook under the notebooks folder, with the kernel each open one uses.

jupyter_create_notebook

Creates a notebook file, with optional initial cells.

jupyter_list_cells, jupyter_read_cell

The cells by index with type, execution count and first line; one cell’s full source and outputs.

jupyter_insert_cell, jupyter_overwrite_cell, jupyter_delete_cell, jupyter_move_cell

Edits. insert_cell takes position: end, or above or below a cell_index. Overwrite and delete return the previous source.

Running cells

Operation What it does

Operation	What it does
`jupyter_execute_cell`	Runs one cell and answers with its outputs when it finishes. `timeout_seconds` (default 600) bounds the wait; past it the kernel is interrupted and the answer says so. A cell that raises answers `success: false` with the exception and the outputs so far.
`jupyter_insert_and_execute_cell`	Inserts a code cell and runs it in one step.
`jupyter_execute_code`	Runs code in the notebook’s kernel without changing the notebook: read a variable, check a package, try a line.
`jupyter_execute_cell_async`, `jupyter_check_execution_status`	A cell that runs for many minutes: the first answers an `execution_id` at once, the second reports `running`, `completed` or `error` with the outputs once it ends. The default limit is one hour per cell.
`jupyter_execute_all_cells`, `jupyter_check_all_cells_status`	The whole notebook in order, in the background, with an `execution_id` to poll: cells done of total, the one running, and each cell’s result. `restart_kernel` starts clean; `stop_on_error` (default true) stops at the first cell that raises.
`jupyter_restart_kernel`, `jupyter_interrupt_kernel`	Restart loses every variable and keeps the cells and outputs; interrupt is Ctrl-C. Either one stops a running notebook, and the run status shows that it was stopped.
`jupyter_kernel_status`, `jupyter_list_kernels`	Whether a kernel is idle or busy; the kernels running with their notebooks, and the kernel types installed.

jupyter_execute_cell

Runs one cell and answers with its outputs when it finishes. timeout_seconds (default 600) bounds the wait; past it the kernel is interrupted and the answer says so. A cell that raises answers success: false with the exception and the outputs so far.

jupyter_insert_and_execute_cell

Inserts a code cell and runs it in one step.

jupyter_execute_code

Runs code in the notebook’s kernel without changing the notebook: read a variable, check a package, try a line.

jupyter_execute_cell_async, jupyter_check_execution_status

A cell that runs for many minutes: the first answers an execution_id at once, the second reports running, completed or error with the outputs once it ends. The default limit is one hour per cell.

jupyter_execute_all_cells, jupyter_check_all_cells_status

The whole notebook in order, in the background, with an execution_id to poll: cells done of total, the one running, and each cell’s result. restart_kernel starts clean; stop_on_error (default true) stops at the first cell that raises.

jupyter_restart_kernel, jupyter_interrupt_kernel

Restart loses every variable and keeps the cells and outputs; interrupt is Ctrl-C. Either one stops a running notebook, and the run status shows that it was stopped.

jupyter_kernel_status, jupyter_list_kernels

Whether a kernel is idle or busy; the kernels running with their notebooks, and the kernel types installed.

Over MCP a call that waits for a cell is held open by the agent for a limited time. For anything longer than a few minutes use the background pair and poll.

Unattended runs

Operation What it does

Operation	What it does
`run_notebook_job`	Runs a notebook on a server of its own: a named server started on `node` with `cpu_cores`, `memory_gb` and `gpus`, the notebook opened with `kernel_name` and run top to bottom, the server stopped when the run ends. Answers a `job_id` at once. The default server, and the tab you may have open in it, are untouched.
`notebook_job_status`	`starting`, `running` with cells done of total, then `completed`, `error` or `cancelled`, with each cell’s result. The notebook file keeps the outputs.
`list_notebook_jobs`, `cancel_notebook_job`	The runs, newest first; stop one and its server.

run_notebook_job

Runs a notebook on a server of its own: a named server started on node with cpu_cores, memory_gb and gpus, the notebook opened with kernel_name and run top to bottom, the server stopped when the run ends. Answers a job_id at once. The default server, and the tab you may have open in it, are untouched.

notebook_job_status

starting, running with cells done of total, then completed, error or cancelled, with each cell’s result. The notebook file keeps the outputs.

list_notebook_jobs, cancel_notebook_job

The runs, newest first; stop one and its server.

Up to three unattended runs run at a time, each on its own server. Thinkube Control polls a run every fifteen seconds and records it in its database. If Thinkube Control restarts during a run, it picks the polling up again; a run whose server was still starting is marked lost and its server stopped.

See it in the IDE

Thinkube IDE carries the Thinkube Notebook View extension. In a terminal, tk-notebook-open <path> shows the notebook in an editor tab: the notebook server’s own single-document page, signed in, on the kernel the agent is using, with copy and paste working. The tab shows one notebook with its toolbar and kernel; the extension’s page setting switches it to the whole of JupyterLab. Ask your agent to show the notebook and it runs that command after opening it. The tab’s title bar has Reload and Open in the browser.

A tab takes a moment to attach after it opens. Until it attaches, a running cell’s progress is written to the file, but the tab shows no change. The tab fills in only when the cell ends. jupyter_kernel_status reports connections, the number of open tabs attached to the kernel. 0 means no tab is attached yet; 1 or more means one is. To let you watch a run, the agent opens the tab and waits until connections is at least one before it runs the cell. Then the progress bar and the printed output appear as they happen. A run with no tab open does not wait, because there is nothing to watch.

A progress bar moves in the tab during a run the agent starts when it is the text form, from tqdm import tqdm. The widget form, tqdm.auto, keeps its progress outside the cell’s outputs and only fills in when the cell ends.

Large outputs

Images and any text output longer than ten thousand characters are written under .outputs/ beside the notebooks, in files named with the date. The answer carries the path in their place. The notebook file keeps the full output.