MCP tools

Every tool ganymede mcp and ganymede serve --mcp offer an agent, with its parameters, as the agent's tools/list shows them. Agents over MCP has setup, and how the tools fit together. With --read-only or --no-execute, the tools that would edit or run stay listed and refuse (Options).

cell_add

Add a cell without running it: Markdown narration (the default), or with mode: recorded a step that ran outside the kernel. With answers set to a request cell's id, it goes below that request and marks it done. Returns the new cell's id.

Parameter	Type	Description
source (required)	string	The cell's source: Markdown, or the command or step it records.
cell_type	markdown, code, raw	Default markdown.
mode	note (Narration), recorded (A step that ran outside the kernel (a shell command, a file the agent wrote), recorded so the notebook tells the whole story)	Default note.
after	string	Insert after this cell id (default: at the end).
path	string	Notebook path; the one last opened when left out.
mark	string	A read mark (from an @@read line) to move past the new cell, as if its reader had added it: for a hook adding a cell on an agent's behalf, so the agent isn't told of it as someone else's.
answers	string	The id of a request cell this cell answers: the cell goes after it (unless after says otherwise), and the request is marked done, so it is no longer reported as a request.

cell_clear_outputs

Leave a code cell's outputs out of the notebook: clears them now and whenever the cell runs again through these tools. For output too large or too private to keep; outputs are the record of the run, so keep them otherwise. keep: true undoes it for the next run.

Parameter	Type	Description
id (required)	string	The code cell's id.
keep	boolean	true keeps the cell's outputs again from its next run.
path	string	Notebook path; the one last opened when left out.

cell_delete

Delete a cell. Refused when someone else changed the cell since your last read; read their change in with notebook_read(since), then redo it.

Parameter	Type	Description
id (required)	string	The cell's id.
path	string	Notebook path; the one last opened when left out.

cell_edit

Replace a cell's source; with run: true, run it after. The replaced source is kept in the cell's metadata.ganymede.agent.history; to remove a secret, delete the cell instead. Refused when someone else changed the cell since your last read; read their change in with notebook_read(since), then redo it.

Parameter	Type	Description
id (required)	string	The cell's id.
source (required)	string	The new source, in place of the whole cell's.
run	boolean	Run the cell after editing it (code cells).
timeout	integer	With run: seconds to wait for the result (default 600). The cell keeps running after a timeout.
keep_outputs	boolean	With run: keep the outputs in the notebook (default: as the cell had it). false leaves them out, as cell_run's keep_outputs.
path	string	Notebook path; the one last opened when left out.

cell_move

Move a cell after another one, or to the top. Refused when someone else changed the cell since your last read; read their change in with notebook_read(since), then redo it.

Parameter	Type	Description
id (required)	string	The id of the cell to move.
after	string	Put the cell after this one; at the top when left out.
path	string	Notebook path; the one last opened when left out.

cell_run

Run code in the notebook's kernel and return its outputs. By default the code is recorded as a new code cell (at the end, or after after); record: false runs it as scratch work that leaves nothing in the notebook and doesn't advance the execution count; it shares the kernel's state, so variables it assigns stay defined.

Parameter	Type	Description
source (required)	string	Code to run.
after	string	Insert after this cell id (default: at the end).
record	boolean	Record the run as a cell (default true). false is a scratch run: it runs in the kernel and leaves nothing in the notebook, but its variables stay defined in the kernel.
timeout	integer	Seconds to wait for the result (default 600). A recorded cell keeps running after a timeout; a scratch run is interrupted.
keep_outputs	boolean	Keep the outputs in the notebook (default true). false records the code but leaves its outputs out of the notebook, now and when it runs again: for output too large or too private to keep. You still get the outputs back.
path	string	Notebook path; the one last opened when left out.

cell_snapshot

Snapshot cells as Markdown to show the user: the code in a fenced block, each chart or image saved as a PNG (or its own format) file and linked by path, tables (table outputs and HTML tables) as Markdown tables, other output as text. The images also come back to you as images, whatever the server's image setting, so use this to look at a chart before describing it. Runs nothing.

Parameter	Type	Description
ids (required)	array of string	Cell ids, in the order to show them.
dir	string	Save images in this directory, relative to this connection's directory, such as journal/snapshots, for a report next to the notebook. By default they go to a directory outside the server root that only you can read.
code	boolean	Include each code cell's source (default true).
max_rows	integer	Rows to keep of a table (default 20).
path	string	Notebook path; the one last opened when left out.

kernel_control

Interrupt, restart or shut down the notebook's kernel.

Parameter	Type	Description
action (required)	interrupt, restart, shutdown	What to do to the notebook's kernel.
path	string	Notebook path; the one last opened when left out.

kernelspecs_list

List the kernels that can run notebooks here, the server's default, and the default for a folder when a .ganymede.toml there or above sets one (kernel = "<name>"). New notebooks in that folder start it unless notebook_open names a kernel.

Parameter	Type	Description
dir	string	The folder to report a default for, relative to this connection's directory (default: that directory).

notebook_open

Open a notebook, creating it if it doesn't exist, and start or join its kernel. Later calls may leave out path. Paths are relative to the directory the reply names: the server's root, or your own folder when ganymede mcp forwards to a server rooted above it, where a leading / starts at the root. Returns a compact view of the notebook.

Parameter	Type	Description
path (required)	string	Notebook path, such as analysis/run.ipynb, relative to this connection's directory (notebook_open names it); a leading / starts at the server root.
kernel	string	Kernelspec name for a new notebook or a new kernel (default: the notebook's own, else its folder's default from .ganymede.toml, else the server's default).
title	string	For a new notebook: a title, written as a first Markdown cell.

notebook_publish

Publish the notebook as one self-contained HTML page to read and share: title, contents, Markdown as prose, charts and tables inline, code folded under each result, light and dark. The page holds only the notebook's cells and outputs (no metadata), makes no network requests and runs no notebook script; the server root, home directory, the server token and mcp_token (each 8 characters or more) are replaced wherever they appear as a whole name. Unless code is hidden or download is false, the page also carries a copy of the notebook with a Download notebook button, with the same replacements and without metadata or recorded parameters. Saves it under the server root, at out relative to this connection's directory (default published/<name>.html beside the notebook), replacing an earlier published page but no other file unless overwrite: true, and returns its path. Runs nothing; run the notebook first so the outputs are current.

Parameter	Type	Description
out	string	Where to save the page, relative to this connection's directory, ending in .html. Default: published/<name>.html beside the notebook.
code	string	How code shows: folded under each result (default), shown, or hidden.
byline	string	A line under the title. Default: today's date.
overwrite	boolean	Replace out even when it isn't an earlier published page.
download	boolean	Put a copy of the notebook in the page, with a Download notebook button: redacted as the page is, without metadata or recorded parameters. Default: on, unless code is hidden.
path	string	Notebook path; the one last opened when left out.

notebook_read

Read a notebook as text: cells with their ids, sources and outputs, then an @@read <mark> line. With since: <mark>, return only the cells others (a person, another agent) added, edited, deleted, moved or ran since the read that gave the mark; your own edits and runs through these tools are left out.

Parameter	Type	Description
path	string	Notebook path; the one last opened when left out.
since	string	A read mark from an earlier read's @@read line: return only the cells others added, edited, deleted, moved or ran since that read. Without path, the mark's notebook. The mark becomes this connection's for that notebook, so its own edits move it.

notebook_requests

List the requests to you that are still open: Markdown cells starting @agent (or @ and your client's name) that a person wrote in a notebook open in this server, through JupyterLab or the apps, and that no cell answers yet. Answer one with cell_add, answers set to its id.

Parameter	Type	Description
path	string	Notebook path; every notebook open in the server under this connection's folder when left out.
edits	boolean	Also list each notebook read, as an @@notebook line, and every other cell a person last changed, as an @@edit line with a hash of its kind and source (a spike, for ganymede mcp watch --edits).

notebook_run_all

Run every code cell in order, after restarting the kernel unless restart: false, and return the notebook.

Parameter	Type	Description
restart	boolean	Restart the kernel first (default true).
timeout	integer	Seconds to wait for every cell to finish (default 600). Cells keep running after a timeout.
path	string	Notebook path; the one last opened when left out.

notebooks_list

List notebooks and directories in a directory.

Parameter	Type	Description
dir	string	Directory relative to this connection's directory (default: that directory); a leading / starts at the server root.

notebooks_search

Search notebooks under a directory (default: this connection's directory, with subdirectories) for cells containing every word of query, ignoring case. Searches sources, and text outputs with outputs: true. Returns each matching cell's notebook, title, index, id, type and an excerpt; read a hit in full with notebook_read. Use it before starting a journal, to find what earlier notebooks found.

Parameter	Type	Description
query (required)	string	Words to find, all of them, in any case and order.
dir	string	Directory to search, with its subdirectories, relative to this connection's directory (default: that directory); a leading / starts at the server root.
outputs	boolean	Search text outputs too, not only sources (default false).
cell_type	string	Only cells of this type: code, markdown or raw.
limit	integer	Most matching cells to return (default 20, at most 200).