MaBoSS Boolean Network Simulator

MaBoSS MCP Server

The Wave 2 integration guide covers summary readouts, named rate editing, persistent run IDs, bounded results and handoff 2.1.

The MaBoSS server exposes stochastic Boolean-model construction, configuration, simulation, analysis, and export through the Model Context Protocol (MCP). It uses pyMaBoSS as its simulation engine and can participate in a verified modelling pipeline from NeKo to MaBoSS to PhysiCell.

The server is distributed in the mcp-biomodelling-servers Python package and communicates over stdio.

Installation and startup

Install all three bio-modelling servers:

python -m pip install mcp-biomodelling-servers

Start the installed MaBoSS server:

mcp-maboss-server

Alternatively, run it in an isolated environment:

uvx --from mcp-biomodelling-servers mcp-maboss-server

The server does not need the separate MaBoSS executable. It validates and simulates models with cmaboss, the compiled engine installed with pyMaBoSS, in a child Python process so a long simulation never blocks the server. Loading a model that the engine rejects fails with the engine's message.

See the repository README for the supported Python versions, complete MCP client configuration, source-checkout instructions, and shared runtime behavior.

Sessions and model state

Every model belongs to a MaBoSS session. Start by calling create_session(), retain the returned session_id, and pass it explicitly when more than one model is active. When session_id is omitted, tools use the active default session.

• create_session creates an isolated in-memory session and may attach a human-readable label.
• list_sessions reports active sessions and whether each has a model or simulation result.
• list_artifact_sessions discovers session artifacts left by earlier server processes.
• set_default_session selects the session used by calls that omit session_id.
• delete_session removes in-memory state and, by default, its artifact files.

Generated BND, CFG, CSV, PNG, and handoff files are stored under the server's session-scoped artifacts/<session_id>/ directory. Use list_generated_files() to obtain their resolved paths instead of guessing them.

Recommended standalone workflow

For a standalone BNET model, use the following order:

1. Call create_session().
2. Convert the BNET with bnet_to_bnd_and_cfg(bnet_path).
3. Load the generated files with build_simulation().
4. Call get_maboss_nodes() and use only the returned node names.
5. Inspect the current configuration with update_maboss_parameters(), get_maboss_initial_state(), and get_maboss_logical_rules().
6. Select a small, biologically meaningful set of outputs with set_maboss_output_nodes(...).
7. Optionally update parameters, initial-state probabilities, or logical rules.
8. Call run_simulation().
9. Read numerical results with get_simulation_result().
10. Render the trajectory with visualize_network_trajectories().
11. Export updated BND/CFG files or a typed PhysiCell handoff when needed.

bnet_to_bnd_and_cfg() writes output.bnd and output.cfg into the session artifact directory. With no paths supplied, build_simulation() automatically loads those files.

A Boolean network with N visible outputs can produce up to 2^N states. Always call set_maboss_output_nodes() before run_simulation(). Selecting only the outputs needed for the scientific question reduces both runtime and result size.

Inspecting and configuring a model

Simulation parameters

Call update_maboss_parameters() without a parameters value to inspect all parameters supported by the loaded model. Supply only the values that should change:

{
  "parameters": {
    "sample_count": 10000,
    "max_time": 100,
    "time_tick": 0.5,
    "thread_count": 4
  },
  "session_id": "SESSION_ID"
}

Common parameters include:

Parameter	Meaning
sample_count	Number of stochastic trajectories
max_time	Simulation time horizon
time_tick	Interval between reported time points
discrete_time	Discrete-time toggle, 0 or 1
thread_count	Number of simulation threads

The server also accepts backend parameters exposed by the loaded MaBoSS version. Unknown parameter names produce a recoverable tool error.

Output nodes

First call get_maboss_nodes(), then provide a non-empty subset:

{
  "output_nodes": ["Apoptosis", "Proliferation"],
  "session_id": "SESSION_ID"
}

Initial-state probabilities

Inspect the existing distribution with get_maboss_initial_state() before changing it.

For one node, provide [P(OFF), P(ON)]:

{
  "nodes": "DNA_damage",
  "probDict": [0.2, 0.8],
  "session_id": "SESSION_ID"
}

For multiple nodes, use JSON-native state/probability records. State-vector order must match the order in nodes, each state must contain only 0 or 1, and the probabilities must sum to 1:

{
  "nodes": ["DNA_damage", "Growth_signal"],
  "probDict": [
    {"state": [0, 0], "probability": 0.4},
    {"state": [1, 0], "probability": 0.6}
  ],
  "session_id": "SESSION_ID"
}

The listed states do not have to cover every possible combination, but states must be unique and each vector must have the same length as nodes.

Logical rules and mutations

• get_maboss_logical_rules returns the current Boolean rules, up to 100 nodes unless selected_nodes is given (truncated reports when more exist). A rule_limitation marks nodes whose custom rate expressions mean the rule alone does not describe their switching; inspect those with get_maboss_nodes.
• change_maboss_rule replaces one node's rule and restores the previous rule if model validation rejects the change.
• get_maboss_mutations reports mutations currently stored in the model.
• simulate_mutation runs a mutant copy without changing the session's base simulation.

For example:

{
  "nodes": ["TP53", "AKT"],
  "state": ["ON", "OFF"],
  "session_id": "SESSION_ID"
}

Mutation states are ON, OFF, or WT. A single state may be applied to all requested nodes, or a state list may be supplied in node order.

Running and reading a simulation

run_simulation() executes the loaded model in a worker thread, stores the pyMaBoSS result in the session, reports MCP progress, and writes a non-empty state-probability table to result.csv.

get_simulation_result() returns both:

• a Markdown state-probability table for the model to read; and
• JSON-native structured content containing the numerical trajectory table.

The same Markdown result is available through maboss://session/{session_id}/result.

Native trajectory images

After run_simulation(), call:

{
  "session_id": "SESSION_ID",
  "until": 50
}

on visualize_network_trajectories.

The optional until parameter is the maximum simulation time displayed. It must be a finite number greater than zero. Omit it to plot the full available trajectory.

The tool:

• delegates trajectory drawing to pyMaBoSS plot_trajectory(until=...);
• uses a tight bounding box and padding so legends outside the axes are not cropped;
• returns the PNG as an MCP ImageContent block with MIME type image/png;
• returns text plus structured metadata for the session, time window, and artifact; and
• saves the exact same PNG bytes as network_trajectory.png in the session artifact directory.

An MCP client must support rendering image content blocks to display the plot inline. The saved artifact remains available when a client presents only the textual or structured part of the result.

Cross-server handoffs

NeKo to MaBoSS

Prefer import_neko_handoff(manifest_path) when the Boolean model comes from the NeKo MCP server. The tool:

• validates the neko-to-maboss manifest and artifact hashes;
• converts the referenced BNET into MaBoSS BND and CFG files;
• verifies the converted node set;
• applies output nodes declared by NeKo when present;
• loads the model only after the complete import succeeds; and
• retains the NeKo provenance for a later PhysiCell handoff.

If the manifest declares no output nodes, call set_maboss_output_nodes() before running or exporting the model.

MaBoSS to PhysiCell

Call export_maboss_handoff(target_cell_type=...) to produce an integrity-protected maboss-to-physicell handoff. It snapshots:

• the current BND and CFG model;
• MaBoSS parameters and selected output nodes;
• an optional non-empty simulation-result CSV;
• the intended PhysiCell cell type and biological context; and
• the complete upstream NeKo lineage, when one was imported.

A standalone MaBoSS model must provide biological_context. A model imported from NeKo may inherit that context. The export refuses to overwrite existing handoff artifacts, so choose a new artifact_prefix for every retained handoff.

Use export_maboss_bnd_cfg() when only standalone MaBoSS files are needed. Use export_maboss_handoff() when PhysiCell needs typed scientific context, integrity metadata, and provenance.

Tool reference

Category	Tools
Sessions	create_session, list_sessions, list_artifact_sessions, set_default_session, delete_session
Import and loading	import_neko_handoff, bnet_to_bnd_and_cfg, build_simulation
Inspection	get_maboss_nodes, get_maboss_initial_state, get_maboss_logical_rules, get_maboss_mutations
Configuration	change_maboss_rule, edit_maboss_readouts, update_maboss_parameters, set_maboss_output_nodes, set_maboss_initial_state
Simulation and analysis	run_simulation, simulate_mutation, get_simulation_result, visualize_network_trajectories
Export	export_maboss_bnd_cfg, export_maboss_handoff
Artifacts	list_generated_files, clean_generated_files

Resources and prompt

The server exposes read-only resources for clients that support MCP resource templates:

URI	Content
docs://maboss/agent_manual	Complete agent operating manual
maboss://session/{session_id}/nodes	Network node names
maboss://session/{session_id}/parameters	Current parameters
maboss://session/{session_id}/initial_state	Initial-state distribution
maboss://session/{session_id}/logical_rules	Boolean rules
maboss://session/{session_id}/mutations	Current mutations
maboss://session/{session_id}/result	Latest in-memory state-probability result (use get_simulation_result(run_id=...) for saved runs)
maboss://session/{session_id}/files	Generated artifact files

maboss_workflow_prompt exposes the same recommended operating rules as an MCP prompt.

Preserved simulation runs

Each successful file-backed run_simulation and simulate_mutation call preserves a unique run_<uuid> artifact set before pyMaBoSS releases its temporary directory:

• Exact BND/CFG inputs sent to the engine (for mutant runs, the mutated copy) and the engine's actual output files.
• Full state-probability and node-marginal CSV tables, including their original time index labelled Time.
• A JSON inventory with session/run identity, run kind, source model revision, requested mutations, effective configuration (parameters, rates, initial state, outputs, readouts), reported timepoints, file sizes and SHA-256 hashes. The inventory is published after its files.

Both tools return the run ID. get_simulation_result(run_id=...) and visualize_network_trajectories(run_id=...) read a saved run from disk after verifying its integrity, including after a server restart, without rerunning the engine. Omitting run_id selects the latest ordinary run of the session and reports the resolved ID; mutant runs never replace that selection, and the base model is not modified. An unknown run ID, or one from another session, is an error rather than a fallback. Each plot is saved under a new <run_id>.plot_<uuid>.png name, so earlier plots are never overwritten.

The legacy result.csv and result resource keep their latest final-snapshot behavior and are not the historical record. Saving results does not fill missing timepoints or validate numerical/biological behavior.

An engine failure or a copy, parsing or publication error fails the operation without rerunning the engine and is recorded as a separate failed_<uuid>.json incomplete record with any available diagnostic files. Partial publication rolls back only that attempt's new links. Previously saved runs remain intact.

Errors and artifact cleanup

Invalid parameters, unknown nodes, missing model state, missing simulation results, and failed scientific operations are returned as MCP tool errors with actionable messages. A caller can correct the arguments or perform the named prerequisite and retry without restarting the server.

clean_generated_files(session_id=...) removes artifacts for one session but keeps its in-memory model. delete_session(clean_files=true) removes both. These operations are destructive; retain any BND, CFG, CSV, PNG, or handoff files needed for reproducibility before calling them.

Further reading

• MaBoSS website and documentation
• pyMaBoSS source
• MCP Python SDK v2 media results
• MCP Python SDK v2 structured output

Artifact storage uses the shared cache root or MCP_BIOMODELLING_ARTIFACT_ROOT, with the MaBoSS/<session_id> namespace. Legacy artifacts remain discoverable. bnet_to_bnd_and_cfg accepts optional parent_manifest (a verified BNET source sidecar or NeKo handoff) and derived_from (the intact parent artifact path for edited copies). Conversion and model exports retain hashes in .lineage.json sidecars. Ordinary provenance does not replace import_neko_handoff or confer approval. See the root README for exact path and provenance semantics.