MCP integration

[jepegit]

@sayanadhikari, any thoughs?

[jepegit]

A concrete proposal, from building one rather than speculating about it.

We prototyped an MCP server for cellpy while working on cellpy-simple-gui#128 — eight tools, driven end to end over the real MCP protocol against cellpy 2.1.2 and the mcp 2.0.0 SDK. Code and notes:

• examples/mcp/server.py — 455 lines, runnable with uv run --script
• design doc, with the measurements

Take or leave any of it. The parts we think are load-bearing are the two findings and the recommendation at the end.

Tool surface

Eight tools covered the whole arc — load, inspect, collect, render, export:

Tool	Returns
list_instruments	loader ids, suffixes, and whether each can run on this machine
load_cell(path, instrument, mass_mg)	a handle, cycle count, mass, and the summary column names
list_cells	what is loaded
describe_plot_families	the 20 summary_plot families, each marked available or with the columns it lacks
collect(kind, …)	a handle, row count, columns, is_grouped, direction counts for ICA/DVA
preview_collection(handle, rows)	a few rows, hard-capped at 20
render(handle, path, kind, …)	a written figure, plus trace types and points plotted
export_collection(handle, path)	a written csv/parquet/json, plus rows and bytes

Three properties mattered more than the list.

Handles, not data. A tool result goes into a model's context window. One collected summary from the demo cell is ~29 kB as CSV and a raw figure can be several MB, so frames stay server-side behind an id and only preview_collection returns rows. The whole eight-call session above put a few kB in front of the model and wrote the rest to disk.

Tool results can carry the traps that documentation struggles with. This is the part we found most interesting for cellpy specifically. render returns trace_types beside points_plotted and rows_collected — so an agent that asked for a density film sees ['histogram2d'] and knows it did not get lines, and one that forgot direction='both' sees 891 of 2328 rows and can notice. Those failure modes produce plausible output, which is exactly what prose warnings are bad at preventing and what a structured result is good at.

Similarly describe_plot_families judges availability on summary_options().columns rather than columns(), so it reports 15 of 20 available on the demo cell and names the missing columns for the rest — the caller never has to discover it by drawing an empty chart. (The summary_options() accessor from #868 is what makes this a five-line tool instead of a lookup table. It has been the single most useful thing in the registry for us.)

Finding 1 — mcp 2.0 does not give a tool a stable session identity

Worth knowing before anyone designs multi-client state. The tool Context has a session, which looks like the key you want. Measured across three calls on one client connection:

{'session_type': 'ServerSession', 'id': 2424878659088, 'request_id': '2'}
{'session_type': 'ServerSession', 'id': 2424878899296, 'request_id': '4'}
{'session_type': 'ServerSession', 'id': 2424878897168, 'request_id': '5'}
distinct session objects across 3 calls: 3

A WeakKeyDictionary keyed on it therefore hands every call a fresh, empty state — and fails silently: the server does not error, it forgets the cell you just loaded and then says "load a cell first". That was our first version.

(There is a second Context class, mcp.server.context.Context, which does have a session_id and is not the one injected into tools. Annotating with it registers without complaint and then fails schema generation with a pydantic error naming neither the import nor the fix. Two hours, that one.)

Consequence for cellpy: under stdio — how MCP servers are normally launched — each client spawns its own process, so process isolation is session isolation and there is nothing to key. That makes cellpy's process-global configuration a much smaller problem than we expected going in. The rule that survives is narrow:

A tool must never call config.reload() or config.set_load_options() — both are process-global. config.override() is contextvar-scoped (thanks to #850) and is the only safe way to vary settings for one call.

Finding 2 — file access is the real commitment

An MCP caller is a language model acting on text it may have read in a file. That is a meaningfully less trustworthy caller than a person typing a path, and load_cell(path) is a read primitive while render(path) and export_collection(path) are write primitives.

The prototype sandboxes all three to one root (CELLPY_MCP_ROOT, defaulting to ~/cellpy_mcp rather than /), resolves and then checks containment, and settles the volume from the string before any filesystem call — the last one because Path.resolve() on \host\share sends Windows off to find host and can block for minutes, and because a boundary that waits on a name server is one a name server could answer differently. Verified refusals: ../escape, C:/Windows/win.ini, \somehost\share\…, /etc/passwd, ~/secrets, and export → .exe.

What the prototype does not answer

• Long loads block. cellpy.get offers no progress and no cancellation, so an agent waits with no signal and an MCP client may time out. This is the gap we would most want closed for this use case.
• No quota. An agent can fill the sandbox with figures.
• No eviction. Cells stay in memory until the process exits.
• Concurrency is untested; one client per process makes it moot for stdio and not for http.

Recommendation

Worth doing — and, we would gently suggest, not inside cellpy yet.

A separate cellpy-mcp package that depends on cellpy can move at the SDK's pace rather than cellpy's release cadence, which matters: mcp 2.0 renamed FastMCP to MCPServer and ships two Context classes with different attributes. It also keeps a long-lived network-facing process, and its security surface, outside the library. If it proves itself there, absorbing it later is easy; extracting it from cellpy after the fact is not.

Happy for the prototype to be a starting point for that package, or to be thrown away — it is small enough for either. And happy to answer questions about any of the above.