NeKo Biological Network Builder

NeKo MCP Server

The Wave 2 integration guide covers bounded diagnostics and the coordinated lightweight-history API.

The NeKo server builds, curates, analyzes, and exports signalling networks through the Model Context Protocol (MCP). It uses NeKo to construct networks from curated interaction databases or existing SIF files, and it preserves topology changes in NeKo's native branching history.

The server is distributed in the mcp-biomodelling-servers Python package and communicates over stdio. A typed, integrity-protected handoff connects a finished NeKo network to the MaBoSS MCP server.

Installation and startup

Install all three bio-modelling servers:

python -m pip install mcp-biomodelling-servers

Start the installed NeKo server:

mcp-neko-server

Alternatively, run it in an isolated environment:

uvx --from mcp-biomodelling-servers mcp-neko-server

The branching history resource renders with the bundled PyGraphviz; no system Graphviz is needed. See the repository README for supported Python versions, complete MCP client configuration, and source-checkout instructions.

Sessions and network state

Every modelling hypothesis should have its own NeKo session. Begin with create_session(), retain the returned session_id, and pass it explicitly to subsequent calls. A newly created session is not automatically selected as the default; call set_default_session() if later calls should be allowed to omit the ID.

{

"label": "TP53-MYC resistance network" }

• list_sessions reports active in-memory sessions, network dimensions, the current default, and history-retention settings.
• list_artifact_sessions discovers exported files from current or previous server processes.
• status returns the node and interaction counts for one session.
• reset_network discards the current network while keeping the session and its settings.
• delete_session permanently removes the in-memory session.

set_default_params() stores completion defaults per session. Previews and global completion reuse all defaults; add_nodes(autoconnect=true) reuses the sign and consensus filters.

Recommended workflow

Use this order for a database-backed network:

1. Call create_session() and retain its ID.
2. Optionally configure reusable connection settings with set_default_params().
3. Build the network with create_network(...).
4. Resolve bimodal edges, which BNET export requires: edit_interactions (operation='set_effect') with evidence where the sign matters, or remove_bimodal_interactions() to delete all remaining ones (this can disconnect the network). When appropriate, also call remove_undefined_interactions().
5. Check connectivity with analyze_connectivity() (isolated nodes and the full component partition).
6. If repair is needed, call preview_connection_impact() before selecting a mutating connection strategy.
7. Inspect the resulting topology and evidence.
8. Use the history tools to compare the new state with earlier alternatives.
9. Export an integrity-protected MaBoSS handoff with export_neko_handoff(...).

During iterative construction, prefer verbosity="summary". Use preview or full only when the actual nodes, interactions, paths, or evidence are needed.

Building a network

create_network() supports two curated database backends:

• omnipath, the default;
• signor.

Create a network from seed genes:

{

"list_of_initial_genes": ["EGFR", "KRAS", "TP53", "AKT1"], "database": "omnipath", "max_len": 2, "path_policy": "one_shortest", "reuse_policy": "discovered_paths", "only_signed": true, "consensus": true, "session_id": "SESSION_ID", "verbosity": "summary" }

The construction parameters are:

Construction may query an external biological database and can take several minutes. The tool reports MCP progress while database resources and the network are being prepared.

An existing SIF can be used instead:

{

"list_of_initial_genes": [], "sif_file": "/absolute/path/input.sif", "database": "omnipath", "session_id": "SESSION_ID", "verbosity": "summary" }

If the server cannot read your file (a host that sandboxes each server), pass the file's complete content as sif_text instead of sif_file. NeKo stores it verbatim in the session artifact directory and records it as the import source.

Additional seed genes may be supplied together with sif_file. A call that cannot complete successfully does not replace a valid network already stored in the session.

Editing and curating the topology

Add or remove nodes and interactions

• add_nodes adds one or more genes in a single call and, by default, autoconnects each new gene to any direct neighbour already in the network (cheap; does not search multi-step paths). Set autoconnect=false to skip.
• remove_gene removes a node and all incident edges.
• remove_interaction removes only the requested directed edge.

Inspect the current network before destructive edits:

{

"session_id": "SESSION_ID", "verbosity": "preview", "max_rows": 50 }

on list_genes_and_interactions.

Gene symbols should match the identifiers returned by the inspection tools. remove_interaction(node_A, node_B) removes node_A → node_B; it does not remove the reverse edge.

Curate interaction signs

• remove_bimodal_interactions removes edges reported as both activating and inhibiting, with their references, and can disconnect the network. Prefer edit_interactions with evidence when an edge's sign matters.
• remove_undefined_interactions removes edges whose effect cannot be mapped to a Boolean activation or inhibition.

These operations simplify later BNET export but change the scientific topology. Inspect the affected network and its history after applying them.

Inspecting topology and evidence

The server offers both concise text and JSON-native structured results:

• list_genes_and_interactions returns node and directed-interaction records.
• filter_interactions filters by effect, source, or target without modifying the network.
• find_paths reports directed paths between two genes up to a bounded length.
• get_references returns literature evidence for interactions involving one or two genes.
• status reports the current dimensions.

For example, inspect inhibitory edges targeting apoptosis:

{

"effect": ["inhibition"], "target": "Apoptosis", "session_id": "SESSION_ID", "verbosity": "preview", "format": "markdown", "max_rows": 50 }

filter_interactions(format="json") changes the model-readable text format; the tool's structured result remains available independently.

Auditing and repairing connectivity

analyze_connectivity() reports isolated nodes—nodes with no incident edges—together with the complete connected-component partition of the network. Use it before a BNET or handoff export.

Scout candidate changes

preview_connection_impact() evaluates possible repair directions without changing the active network:

Example:

{

"method": "relax_max_len", "session_id": "SESSION_ID", "verbosity": "preview", "format": "markdown" }

The simulation methods operate on a copy. Their predicted changes are not committed to the session.

Apply a selected strategy

See NeKo's concise connection-strategy guide to choose the topology and path/reuse policies that match the research question.

bridge_components() connects two explicit groups:

{

"comp_a": ["EGFR", "KRAS"], "comp_b": ["TP53", "BAX"], "max_len": 2, "mode": "OUT", "only_signed": true, "consensus": true, "session_id": "SESSION_ID" }

comp_a/comp_b must be Gene Symbols (e.g. from a component's nodes list in analyze_connectivity()'s output), never the numeric component_id that analyze_connectivity() reports for each component - that ID is a report label, not a valid gene name.

mode is OUT, IN, or ALL.

connect_targeted_nodes() supports:

• connect_to_upstream_nodes;
• connect_subgroup.

apply_global_connection() supports:

• complete_connection, with explicit path_policy and reuse_policy;
• connect_network_radially, with direction="OUT" or "IN";
• connect_as_atopo, with strategy_mode="radial" or "complete" and an optional outputs list of gene symbols to anchor the topology. This strategy loops until the network is connected to every declared output, so its cost is open-ended on large networks.

The database-backed connection tools can be expensive — complete_connection is O(N^2) over every node pair, and connect_as_atopo cost is open-ended. Reinspect components and compare history states after every selected strategy.

Branching network history

NeKo automatically records snapshots for its supported topology-changing operations. The MCP server exposes that native history directly, so undo, redo, checkout, and comparison preserve the exact NeKo network states.

List states

list_network_history() returns:

• the exact current state ID;
• retained state IDs;
• parent and child relationships;
• node and edge counts for every state;
• the configured retention limit.

State IDs are identifiers, not list positions. Always obtain them from list_network_history() before navigation or comparison.

Navigate

Use the single navigate_network_history() tool:

{

"action": "checkout", "state_id": 3, "session_id": "SESSION_ID" }

The supported actions are:

Navigation does not delete other saved states. If an older state is checked out and then modified, NeKo retains the previous future and records the new topology on a separate branch.

Compare without navigating

compare_network_states(state_a, state_b) reports added and removed nodes and interactions without changing the currently checked-out state:

{

"state_a": 2, "state_b": 5, "session_id": "SESSION_ID" }

Configure retention

set_network_history_limit(max_states) sets the per-session policy:

• null keeps an unbounded history;
• an integer must be at least 2;
• a policy set before construction applies when a network is created;
• lowering the limit may immediately and irreversibly prune older snapshots.

Call list_network_history() before reducing the limit.

Render the history

Read:

neko://session/{session_id}/history

to obtain read-only HTML containing NeKo's inline SVG history diagram. This resource does not change the checked-out state. The server renders NeKo's history digraph with the bundled PyGraphviz rather than an external dot executable; a rendering failure is returned as a resource error.

Exp