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. "highdemand"). 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. scenarioid is required; omit parametersetid to read across all parameter sets.

Create an agent instance in a scenario. nodetypeid (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. propertyid may be a property name or ID; omit parametersetid 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. setproperties replaces the entire overlay for the target parameter set — to change a single value use setparametervalue 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 settimeseriesvalue. 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 scenarioid (scenario-scoped) or twinid (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 (setproperties 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 translateelements using keys like '{chartid}:name', '{chartid}:series:{seriesid}:displayname', and '{widgetid}: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 searchnodes, so this is how you discover a diagram's ID before calling updatediagram, addtodiagram, addrelationshipstodiagram, removefromdiagram, or deletediagram. Filter by level (metamodel for type diagrams, model for instance diagrams), name, or folder. For simulation dashboards use listsimulationdiagrams 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 twinid.

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 getagentdetails 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 cascaderelationships to false to fail if the node has any relationships.

Update labels, descriptions, or properties on existing nodes. Use setlabel/setdescription to update core fields, setproperties for key-value pairs, and removeproperties 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 defaultvalue is then a Rhai formula evaluated each timestep), and the node type can carry an actscript — 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 getmetamodel to check, or addnodetype 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 getmetamodel to check existing types.

Add a new relationship type to the metamodel. After creating it, use addallowedconnection 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 actscript, plus a self-describing "scripting" block documenting the available simulation functions (getconnected, sumprop, agent.getprop/setprop, …) 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 updatedat 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 getrelationships 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 findsimilarnodes 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 getnodedetails for full information. Each summary now includes an updatedat timestamp (ISO 8601 UTC) for change detection.

Run the simulation and read back the COMPUTED time series for a scenario. Unlike gettimeseries (which returns only stored input cells — manual entry or live data), this evaluates the Rhai property formulas and act scripts on demand and returns the resulting per-agent, per-property, per-timestep values, each with its simulated time, plus formula diagnostics. This is the only way to read formula-driven results via the API: they are computed on the fly and never persisted. scenarioid is required; parametersetid defaults to the scenario's twin's default parameter set. Use agentinstanceid, propertyid, mintimestep, and maxtimestep to scope large series. Check the diagnostics field (formula/act-script compile and runtime errors, cycles, unresolved dependencies) when results look wrong or empty.

Update tags on any model element (node, relationship, node type, relationship type, diagram, or folder). Replaces all existing tags. Applied immediately.

Create a new diagram for visualizing model elements. Use diagramtype 'metamodel' for M2 type diagrams, 'model' for M1 instance diagrams. Applied immediately.

Create a navigation tree (ModelTree): a named, ordered tree structure over the graph, used as a reading-oriented browse structure (Reader Workspace, publishing site nav, report chapter order). A tree is an ordered list of branches; each branch may have a label, description, a seed (a filter expression selecting its node(s) — e.g. {"OfType":{"typeid":"<id"}}, {"HasId":{"ids":"<node-id"}}, {"FilterRef":{"filterid":"<id"}}), an expansion (follow a relationship from the seed), an ordering, and nested children. Use listtrees to discover existing trees. Applied immediately.

Update a navigation tree's name, description, or branch structure. setbranches replaces the whole branch forest (same JSON shape as createtree's branches). Accepts tree ID or name. Pass a locale to write name/description into a non-default language's translation layer. Applied immediately.

Delete a navigation tree. Terminal — does not cascade to any model data (only the tree's reading structure is removed). Accepts tree ID or name. Applied immediately.

List the model's navigation trees. Trees live in their own collection (not returned by searchnodes), so this is how you discover a tree's ID before calling updatetree or deletetree. Returns id, name, description, folderid, tags, and branchcount (number of top-level branches). Filter by name or folder.

Create a stored filter with a composable expression. Expressions: {"OfType":{"typeid":"<id"}}, {"HasTag":{"tag":"foo"}}, {"NameMatches":{"operator":"Contains","value":"foo"}}, {"And":...}, {"Or":...}, {"Not":expr}, {"InFolder":{"folderid":"<id","recursive":true}}, or "All". Applied immediately.

Update an existing node type: rename, recolor, change description, or add new properties. For simulation, setactscript sets or clears the node type's Rhai act script, and updateproperties edits existing properties in place — including making a property computed or changing its Rhai formula. Applied immediately and broadcast to all connected users.

Update an existing relationship type: rename, recolor, change description, or add new properties. Applied immediately and broadcast to all connected users.

Add nodes or node types to a diagram with auto-grid layout. For model diagrams use node IDs or auto-IDs (e.g. REQ-1); for metamodel diagrams use node type IDs. Applied immediately.

Delete a diagram and all its element placements. Does NOT delete the underlying nodes or relationships — only the visual representation. Applied immediately.

Update labels, descriptions, or properties on existing relationships. Applied immediately and broadcast to all connected users. Relationship IDs accept both UUIDs and auto-IDs (e.g., "CON-5").

Delete a stored filter. Does not delete any model data. Applied immediately. Accepts filter ID or name.

Update an existing diagram's name or description. Applied immediately. Accepts diagram ID or name.

Move model elements into a folder (or to root by omitting folderid). Supports nodes, relationships, node types, relationship types, diagrams, and folders. Applied immediately.

Remove an allowed connection constraint, revoking permission for a relationship type to connect specific node type pairs. Applied immediately.

Update the model's top-level name or description. Applied immediately.

Auto-show all relationships between elements already placed on a diagram. For model diagrams shows M1 relationships; for metamodel diagrams shows allowed connections. Applied immediately.

Remove nodes or node types from a diagram. Also removes connected relationship visualizations on that diagram. Does NOT delete the underlying elements. Applied immediately.

Rename an existing folder and optionally update its description. Applied immediately.

Create a new folder for organizing model elements. Use layer 'metamodel' for node/relationship type folders, 'model' for node/relationship/diagram folders. Applied immediately.

Remove a node type from the metamodel. Also cascades to remove all M1 instances of that type and their relationships. Applied immediately. Use with caution — cannot be undone via MCP.

Remove a relationship type from the metamodel. Also removes all relationships of that type from M1. Applied immediately. Use with caution.