PhysiCell Configuration Builder

PhysiCell MCP Server

The Wave 2 integration guide covers stored configuration readback, typed inputs, required-substrate visibility and portable bundles.

The PhysiCell server creates, loads, inspects, modifies, validates, and exports PhysiCell configuration files through the Model Context Protocol (MCP). It uses the physicell-settings package to build PhysiCell_settings.xml, Cell Rules CSV files, and PhysiBoSS intracellular-model settings.

This server is a configuration builder, not a PhysiCell simulation runtime. It does not launch a PhysiCell executable or analyze tissue-simulation output. Exported files must be placed in an appropriate PhysiCell project and executed with that project's compiled application.

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 PhysiCell server:

mcp-physicell-server

Alternatively, run it in an isolated environment:

uvx --from mcp-biomodelling-servers mcp-physicell-server

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

Sessions and configuration state

Use one PhysiCell session per independent model. create_session() selects the new session as the default unless set_as_default=false is supplied:

{

"set_as_default": true, "session_name": "hypoxic_tumor_v1" }

Pass the full returned session_id explicitly whenever multiple configurations are active. set_default_session() also accepts an unambiguous eight-character session prefix.

• list_sessions reports active sessions, configuration presence, component counts, loaded-XML provenance, PhysiBoSS counts, and workflow progress.
• list_artifact_sessions discovers files retained from current or previous server processes.
• get_workflow_status and get_simulation_summary return the same workflow state and recommended next steps.
• delete_session permanently removes the in-memory session state.

Workflow progress records which configuration-building steps have been performed. It does not prove that parameter values are biologically justified, that all required custom code exists, or that the exported model will execute successfully in a particular PhysiCell project.

Build a new configuration

Use the following order:

1. Call create_session().
2. Store the modelling objective with analyze_biological_scenario().
3. Define space, mesh, dimensionality, and duration with create_simulation_domain().
4. Call add_single_substrate() once for every diffusible substrate.
5. Call add_single_cell_type() once for every cell population.
6. Configure cell parameters and every required cell/substrate interaction.
7. Discover exact signal and behavior names.
8. Add as many signal-behavior rules as the model requires.
9. Optionally attach and configure intracellular MaBoSS models through PhysiBoSS.
10. Inspect the summary and read-only resources.
11. When cell rules exist, export their CSV first and the XML second.

analyze_biological_scenario() stores the supplied text as session context. It does not infer cell types, substrates, parameter values, or rules automatically.

Recreating the domain resets the model

create_simulation_domain() creates a fresh PhysiCellConfig and replaces the configuration currently stored in the session. Calling it after substrates, cell types, rules, or PhysiBoSS models have been added discards those components. Use the parameter patch tools—not a second domain call—to revise an existing configuration.

Define the simulation domain

For a planar model:

{

"domain_x": 2000, "domain_y": 2000, "use_2d": true, "dx": 20, "max_time": 7200, "session_id": "SESSION_ID" }

In 2D mode, the z extent is one mesh voxel (dx) and PhysiCell's planar mode is enabled. For a full 3D model, set use_2d=false and provide a positive domain_z.

The domain is centered on the origin. max_time is expressed in minutes and dx in micrometers. Smaller mesh spacing increases spatial resolution and typically increases the cost of the eventual PhysiCell simulation.

Add substrates and cell types

Substrates

Call add_single_substrate() separately for oxygen, nutrients, drugs, or other diffusing fields:

{

"substrate_name": "oxygen", "diffusion_coefficient": 100000, "decay_rate": 0.01, "initial_condition": 38, "units": "mmHg", "dirichlet_enabled": true, "dirichlet_value": 38, "session_id": "SESSION_ID" }

When Dirichlet boundaries are enabled, the tool applies the value to the x and y boundaries and also to z boundaries in 3D. When dirichlet_value is omitted, the initial condition is used.

Cell types

Use get_available_cycle_models() to inspect valid cycle names, then call add_single_cell_type() once per population:

{

"cell_type_name": "cancer_cell", "cycle_model": "Ki67_basic", "session_id": "SESSION_ID" }

Substrates and cell types must exist before tools can configure a specific cell/substrate pair or attach an intracellular model.

Flat partial-update semantics

The public configuration tools currently use flat optional arguments. Supply only the values that should change. The deferred nested-parameter-object redesign is not part of this release.

Each patch is prepared on a separate configuration copy and published only after it succeeds. A failed patch leaves the active configuration unchanged.

Patch cell parameters

configure_cell_parameters() supports:

• volume_total;
• volume_nuclear;
• fluid_fraction;
• motility_speed;
• persistence_time;
• motility_enabled;
• apoptosis_rate;
• necrosis_rate.

At least one value is required. Every omitted value is preserved.

{

"cell_type": "cancer_cell", "motility_speed": 0.8, "motility_enabled": true, "session_id": "SESSION_ID" }

The same cell type can be revised later without repeating its motility values:

{

"cell_type": "cancer_cell", "apoptosis_rate": 0.001, "session_id": "SESSION_ID" }

That second call preserves the earlier motility speed and enabled state. Repeat the tool independently for every cell type that needs configuration.

Patch one cell/substrate interaction

set_substrate_interaction() targets one existing cell-type/substrate pair:

{

"cell_type": "cancer_cell", "substrate": "oxygen", "uptake_rate": 10, "session_id": "SESSION_ID" }

At least one of secretion_rate or uptake_rate is required. An omitted rate is preserved, as are the existing secretion target and net export rate. Repeat the tool for every required pair or call it again later to revise one rate. The result contains the interaction values actually stored for the pair, the configuration revision and changed, which is false when the requested values already matched.

Signals, behaviors, and Cell Rules

Use:

• list_all_available_signals() for environment, contact, intracellular, and other signals available in the current configuration;
• list_all_available_behaviors() for configurable cell behaviors;
• get_available_cycle_models() for cell-cycle identifiers.

The signal and behavior discovery tools return descriptions and requirements as structured data. Use their exact names when adding a rule.

add_single_cell_rule() adds one Hill-function relationship:

{

"cell_type": "cancer_cell", "signal": "oxygen", "direction": "decreases", "behavior": "apoptosis", "saturation_value": 0, "half_max": 5, "hill_power": 4, "session_id": "SESSION_ID" }

direction is increases or decreases. half_max and hill_power must be positive. Call the tool repeatedly for every signal-behavior relationship.

Modify an existing XML configuration

Use this workflow:

1. Call validate_xml_file(filepath).
2. If the structured result reports valid=true, call load_xml_configuration(filepath).
3. Inspect it with analyze_loaded_configuration().
4. Use list_loaded_components() for substrate, cell-type, or PhysiBoSS details.
5. Apply targeted patches and additions.
6. Inspect get_simulation_summary().
7. Export to a session-scoped filename.

validate_xml_file() is read-only. A well-formed validation request for an invalid XML file returns a successful tool result with valid=false and an error description. The validation operation succeeded; the file did not pass validation.

load_xml_configuration() validates and parses a candidate configuration before replacing the session state. A missing, invalid, or unloadable file does not replace the current configuration.

analyze_loaded_configuration() returns source provenance, domain information, component names, existing rules, PhysiBoSS models, and modification guidance. list_loaded_components(component_type=...) accepts substrates, cell_types, physiboss, or all.

PhysiBoSS integration

PhysiBoSS support must be available in the installed physicell-settings package. A target PhysiCell cell type must exist before an intracellular MaBoSS model can be attached.

Preferred verified handoff

Export a maboss-to-physicell handoff from the MaBoSS MCP server, then call:

{

"manifest_path": "/path/to/maboss_to_physicell.handoff.json", "artifact_prefix": "cancer_cell_maboss_v1", "replace_existing": false, "session_id": "SESSION_ID" }

on import_maboss_handoff.

If this server cannot read MaBoSS's files (a host that sandboxes each server), replace manifest_path with handoff_bundle, the object returned by MaBoSS export_handoff_bundle. See Hosts that sandbox each server.

The tool:

• verifies the manifest, BND, CFG, optional result table, and artifact hashes;
• verifies the complete upstream NeKo lineage when present;
• checks the exact Boolean node and output-node contracts;
• checks that the declared target cell type exists;
• copies the verified artifacts into the PhysiCell session;
• attaches the candidate model only after the complete import succeeds; and
• stores a separate MaBoSS context for the target cell type.

Use a new artifact_prefix for every retained import. Existing import artifacts are not overwritten.

Importing models for different target cell types preserves independent contexts. If the target already has an intracellular model, import fails unless replace_existing=true is supplied. Explicit replacement resets that target's previous PhysiBoSS settings, input links, output links, and mutations.

Configure settings and biological mappings

After import, patch the target's timing and inheritance:

{

"cell_type": "cancer_cell", "intracellular_dt": 6, "time_stochasticity": 0, "inheritance_global": true, "session_id": "SESSION_ID" }

configure_physiboss_settings() also supports scaling and start_time. At least one value is required and every omitted setting is preserved. The tool can be called repeatedly for the same target or separately for several target cell types.

Then call repeatedly as needed:

• add_physiboss_input_link to map a PhysiCell signal to a Boolean node and return the stored input mapping;
• add_physiboss_output_link to map a Boolean node to a PhysiCell behavior;
• apply_physiboss_mutation to fix a Boolean node to 0 or 1.

Input and output link actions are activation or inhibition. Discover exact PhysiCell signal and behavior names with the discovery tools, and use exact Boolean node names from the MaBoSS context.

MaBoSS output nodes, parameters, and simulation summaries are preserved as context. They are not au