MCP API Reference

Get full details for agents by ID, including baseline property values grouped by parameter set (property names resolved from the agent's node type).

Create a parameter set within a twin — a named bundle of input-value overrides on an axis orthogonal to scenarios. Use a stable lowercase name (e.g. "high_demand"). Applied immediately and broadcast to connected users in real-time.

Update a simulation diagram's name and/or description. Applied immediately and broadcast to connected users in real-time.

List links — the connections between agents within a scenario (the simulation counterpart of relationships). Returns endpoints with resolved agent labels and link property values. Filter by scenario, relationship type, or endpoint.

Update a parameter set's name and/or description. Applied immediately and broadcast to connected users in real-time.

Delete a simulation diagram and its placements and widgets. Applied immediately and broadcast to connected users in real-time.

List simulation diagrams — the visual canvases for a scenario or twin that show agents, links, and dashboard widgets. Filter by twin or scenario.

Delete a parameter set along with its overlay values and time series. A twin's default parameter set cannot be deleted. Applied immediately and broadcast to connected users in real-time.

Read time-series values: an agent's property value at each timestep, for a scenario and parameter set. This is the simulation spreadsheet data. scenario_id is required; omit parameter_set_id to read across all parameter sets.

Create an agent instance in a scenario. node_type_id (the agent's type) is required and defines its property and behavior schema. Baseline properties may be keyed by name or ID and target the given (or twin-default) parameter set. Applied immediately and broadcast to connected users in real-time.

Set one cell of the simulation spreadsheet: an agent's property value at a given timestep, in a scenario and parameter set. property_id may be a property name or ID; omit parameter_set_id for the twin default. Applied immediately and broadcast to connected users in real-time.

Create a simulation twin — a Live Twin container scoped to a subset of node types, optionally attached to a model node. Scenarios, parameter sets, and agents are created inside it. Applied immediately and broadcast to connected users in real-time.

Update an agent's label, description, or baseline property overlay. set_properties replaces the entire overlay for the target parameter set — to change a single value use set_parameter_value instead. Applied immediately and broadcast to connected users in real-time.

Set a single baseline value for an agent property in a specific parameter set — the field a slider or checkbox would write. For per-timestep values use set_time_series_value. Applied immediately and broadcast to connected users in real-time.

Update a twin's name and/or description. Applied immediately and broadcast to connected users in real-time.

Delete an agent instance along with its links, time series, and diagram placements. Applied immediately and broadcast to connected users in real-time.

Clear a single baseline overlay value for an agent property in a parameter set (reverts to inheriting the default set). Applied immediately and broadcast to connected users in real-time.

Create a scenario (what-if projection) within a twin, with its own timeline. The step size dt must be 1/N for a positive integer N (e.g. 1, 0.5, 0.25). Applied immediately and broadcast to connected users in real-time.

Update a scenario's name, description, or timeline (start time, end time, dt). A changed dt must still be 1/N for a positive integer N. Applied immediately and broadcast to connected users in real-time.

Delete a scenario along with its agents, links, and time series. Applied immediately and broadcast to connected users in real-time.

Create a simulation diagram — a visual canvas for a scenario or twin. Provide exactly one of scenario_id (scenario-scoped) or twin_id (twin-level, spans all scenarios). Agent/link placement and widgets are added in-app. Applied immediately and broadcast to connected users in real-time.

Update a link's description and/or property values (set_properties replaces the link's properties). Applied immediately and broadcast to connected users in real-time.

Clear one time-series cell (an agent's property value at a timestep). Applied immediately and broadcast to connected users in real-time.

Get the widgets on a simulation diagram (dashboard) with their IDs and current text — charts (name, axis labels, per-series display names) and slider/checkbox/option/text/parameter-set-chooser controls (label). These widgets live only on the diagram and have no model-tree presence, so this is the only way to discover their IDs. Use it to translate a dashboard: read the contents, then write translations with translate_elements using keys like '{chart_id}:name', '{chart_id}:series:{series_id}:display_name', and '{widget_id}:label'.

List simulation twins. A twin is a Live Twin container scoped to a subset of node types, optionally attached to a model node. Returns each twin's scope, default parameter set, and scenario/parameter-set counts.

Create a link between two agents in a scenario — the simulation counterpart of a relationship. The relationship type and both agents must already exist. Applied immediately and broadcast to connected users in real-time.

List the model's diagrams with their IDs, names, and levels. Diagrams aren't returned by search_nodes, so this is how you discover a diagram's ID before calling update_diagram, add_to_diagram, add_relationships_to_diagram, remove_from_diagram, or delete_diagram. Filter by level (metamodel for type diagrams, model for instance diagrams), name, or folder. For simulation dashboards use list_simulation_diagrams instead.

List scenarios within twins. A scenario is a what-if projection with its own timeline (start time, end time, step size dt). Returns timeline parameters, the computed timestep count, and agent/link counts. Filter by twin_id.

List the parameter sets in a twin. A parameter set is a named bundle of input values on an axis orthogonal to scenarios — a simulation run is keyed by (scenario, parameter set). Shows which set is the twin's default.

Delete a link and its diagram placements. Applied immediately and broadcast to connected users in real-time.

List agent instances in a scenario. Each agent is an instance of a node type living in one scenario. Returns summaries; use get_agent_details for baseline property values. Filter by scenario, twin, node type, or name.

Delete a twin and everything inside it — its scenarios, parameter sets, agents, links, and time series. Applied immediately and broadcast to connected users in real-time.

Delete one or more nodes. By default, all connected relationships are also deleted (cascade). Set cascade_relationships to false to fail if the node has any relationships.

Update labels, descriptions, or properties on existing nodes. Use set_label/set_description to update core fields, set_properties for key-value pairs, and remove_properties to clear values. Node IDs accept both UUIDs and auto-IDs (e.g. REQ-42).

Add a new node type (entity type) to the metamodel. Do this before creating nodes of that type. You can define custom properties with data types. For simulation, a property can be marked computed (its default_value is then a Rhai formula evaluated each timestep), and the node type can carry an act_script — a Rhai script run per agent per timestep that drives behaviour.

Find nodes with similar names that might be duplicates. Uses string similarity matching. Useful before creating new nodes to avoid duplication.

Create new node instances. Node type must already exist in the metamodel (use get_metamodel to check, or add_node_type to create). Changes are applied immediately and broadcast to all connected browser users in real-time.

Define an allowed connection pattern between node types for a relationship type. All three (relationship type, source node type, target node type) must already exist in the metamodel. Use get_metamodel to check existing types.

Add a new relationship type to the metamodel. After creating it, use add_allowed_connection to specify which node types can be connected with it.

Get the model's schema (metamodel). Returns all node types, relationship types, their properties, allowed connections, and instance counts. Always call this first to understand what the model contains. For simulation models it also reports each property's computed flag and Rhai formula and each node type's act_script, plus a self-describing "scripting" block documenting the available simulation functions (get_connected, sum_prop, agent.get_prop/set_prop, …) so you can author formulas correctly.

Get complete details for one or more nodes by their IDs. Returns all properties, description, and metadata. Accepts both UUIDs and auto-IDs (e.g. REQ-42). Each node also includes an updated_at timestamp (ISO 8601 UTC) marking when it last changed, so external tools can skip nodes that haven't changed since they last looked.

Delete one or more relationships by their IDs. Use get_relationships to find the relationship IDs first.

Get model-wide statistics: node and relationship counts by type, most connected nodes, and property completeness. Useful for a quick model overview.

Create relationships between existing nodes. Both source and target must exist. The relationship type must exist in the metamodel and have an allowed connection defined for the given source/target node types.

Merge duplicate nodes into a single node. All relationships from merged nodes are redirected to the kept node. The merged nodes are then deleted. Use find_similar_nodes to identify candidates.

Find relationships (connections) between nodes. Filter by relationship type, source node, target node, or node types. Source and target IDs accept both UUIDs and auto-IDs (e.g. REQ-42).

Search for nodes (instances) in the model. Filter by type, name, description, property values, or folder. Returns summaries — use get_node_details for full information. Each summary now includes an updated_at timestamp (ISO 8601 UTC) for change detection.