MCP API Reference

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).

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).

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

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.

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.

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

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.

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.

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.

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.

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

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.

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.

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

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.

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.

Update a parameter set's name and/or description. 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.

Delete a scenario along with its agents, links, and time series. 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 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.

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.

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.

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

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.

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 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.

Delete a simulation diagram and its placements and widgets. 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.

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.

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.

Delete an agent instance along with its links, time series, and diagram placements. 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.

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

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.

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.

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.

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

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.

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.

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 link and its diagram placements. 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.

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.

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.

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 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.

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.

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.

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.

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.

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.

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

Rename an existing folder and optionally update its description. 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 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").

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.

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 a relationship type from the metamodel. Also removes all relationships of that type from M1. Applied immediately. Use with caution.

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

Set the tags on a model element. This REPLACES every tag already on the element, so read its current tags first and send them back alongside the new ones — otherwise you silently drop the tags that were there. Tags come back from searchnodes, getnodedetails, getrelationships, getmetamodel and the list tools; listtags shows the vocabulary already in use.

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.

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.

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

Delete a diagram and all its element placements. Does NOT delete the underlying nodes or relationships — only the visual representation. 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.

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

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

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

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

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

List every tag in use across the model, with how many elements carry each one. Counts cover all taggable element kinds — nodes, relationships, node and relationship types, diagrams, grid views, folders, filters, navigation trees, renderings, publications, assets, and the simulation elements. Capitalisation is ignored, so 'Persistence' and 'persistence' count as one tag. Call this before tagging so you reuse the vocabulary already in the model instead of introducing a near-duplicate spelling.

Read what's inside an asset's file. PDFs come back as extracted text; text, JSON, CSV, XML and Markdown come back as-is; PNG, JPEG, GIF and WEBP come back as an image the AI can look at. This is how an AI assistant reads a requirements document, a datasheet or a spec you've attached to the model. Use listassets first to find the asset's id.

Create an asset element — a place in the model for an image, document or other file. This creates the element only; no file is attached yet. Call uploadassetfile afterwards to attach the content. The response gives you the new asset's id.

Delete an asset. This also removes the stored file and takes the asset off any diagrams it was placed on. It can be undone from version history. Applied immediately.

Rename an asset, change its description, or move it to another folder. This does not touch the attached file — use uploadassetfile to replace the content, or deleteasset to remove the asset altogether. Applied immediately.

Find assets in a model by label, filename, file type, or folder. Assets live in their own collection rather than alongside nodes, so searchnodes will not find them — use this instead. Each result gives the asset's id, label, original filename, content type, size in bytes, and whether a file is actually attached. Call this first to get an asset id for getassetcontent.

Attach a file to an existing asset by pointing Metapad at a public URL. The server downloads the file, stores it, and everyone with the model open sees it appear. Note this fetches from a URL — it does not take raw file bytes. To upload a file directly from your machine, use the REST API instead — Upload Asset for a new asset, or Attach Asset File to put a file on one that already exists.

List the model's folders. Each one comes back with its id, name, which layer it belongs to (the metamodel or the model itself), what kind of content it holds, and its parent folder. Use this to look up a folder before calling anything that takes a folderid — createnodes, addnodetype, movetofolder, creatediagram, createfilter, createasset.

Change a stored filter's name, description, or the expression that decides what it matches. The new expression replaces the old one outright rather than being added to it. Applied immediately.

Write translations into the model. Each call merges with what's already there rather than replacing it, so you can work through a large model in batches without losing earlier work.

Collect every piece of text in the model that can be translated, in one place. That means the model's own name and description, your types and their properties, every node and relationship with its labels, descriptions and property values, diagrams, grid views, folders, filters and assets, the whole publishing layer (navigation trees and each branch's title and lead text, document renderings and their document bodies, publications and their homepages), and the entire simulation layer down to dashboard chart titles, axis labels and slider captions.

Add a language to the model so it can be translated into. The language then appears in the model's language settings and becomes a valid target for translateelements.

Delete a rendering. Nothing in the model itself is affected — only the page template goes. Any publication that had selected it will report an unresolved selection until you pick another one. Applied immediately.

Render one page of a publication exactly as it will be published, with a report on what worked.

Change a rendering's name, description, or document. The new document replaces the old one entirely rather than being merged into it — send the whole template, not just the part you changed. Applied immediately.

Publish a publication by fixing it to a particular version of the model. Readers then see that version as a stable snapshot, so they aren't reading a half-finished edit while you work on the model.

Read a navigation tree's whole branch structure. Branches aren't nodes, so no other tool reaches them — listtrees only tells you how many there are. For each branch, nested as deep as it goes, you get its id, title, lead text, what seeds it, any elements attached by hand, how it expands along relationships, how it's ordered, its child branches, and the elements it currently holds.

List the model's publications — the assembled sites and PDF reports built from navigation trees, per-type renderings and a homepage. Publications are kept separately from nodes, so searchnodes won't find them; this is how you get a publication's id before updating, rendering, publishing or deleting it. Each result gives id, name, slug, description, which trees form the site map, which rendering presents each type, any connected report services, whether readers see auto-IDs, folder, tags, and whether it has been published.

Create a publication — the thing that turns your model into a readable site or a PDF report. A publication decides three things: which navigation trees form the site map, which rendering presents each type of element, and what the homepage says.

Render a whole publication — every page, in reading order, in one go. This is the same assembly the PDF and the Markdown download use, so what comes back is the real artifact rather than an approximation.

Delete a publication. Nothing in the model itself is affected — the trees, renderings and elements it drew on all stay. Only the assembly goes. Applied immediately.

Create a rendering — the page template for one node or relationship type. Every element of that type is presented through it, so you write the shape of the page once rather than writing each page.

List the model's renderings — the page templates that say how elements of a given type are presented on Reader pages, published site pages and PDF chapters. Renderings are kept separately from nodes, so searchnodes won't find them; this is how you get a rendering's id before updating, previewing or deleting it. Each result gives id, name, the type it targets, description, folder, tags, and how long its document is.

Render one rendering against one element and get the resulting page back, together with a report on what worked. You don't need a publication for this — it's the tool to use while writing a rendering, because createrendering and updaterendering write the document blind.

Change a publication's name, slug, description, homepage, site map, per-type rendering selection, connected report services, or whether readers see auto-IDs.

Replace one passage inside a long text, in place. You send the exact wording to remove and what should stand in its place; every other character stays as it was — so a long description or a published document can't quietly lose a paragraph to a rewrite. Prefer it over updatenodes for anything longer than a couple of sentences.