poietic-mcp
An MCP server that lets an agent read, edit, validate, simulate and export Poietic Stock and Flow designs alongside a human working in Poietic Playground.
Discover the metamodel schema (object types, traits, attributes, edge types) with
poietic_metamodel.Read a design as normalized JSON — nodes, edges, and unstructured data.
Bind a current design session with
poietic_use_design, snapshotted with a content-hash fingerprint guard against external edits.Create empty designs (
poietic_new_design), optionally importing planes.Build and edit models: add nodes (Stock, FlowRate, Auxiliary), connect Flow/Parameter edges, set/unset attributes, remove objects.
Auto-wire required Parameter edges and drop stale ones (
poietic_auto_parameters).Lay out the canvas with circle or alignment modes (
poietic_arrange).Validate designs (formula/parameter errors) before simulating.
Run simulations with time-range, solver (euler/rk4), variable, and parameter overrides; get per-variable summaries, capped sample rows, or full CSV output.
Export SVG diagrams and Graphviz DOT, and export/import planes between design files.
Undo/redo one transaction per tool call.
Read resources (metamodel, builtins, current design, current diagram SVG) and use the
build_stock_and_flow_modelprompt for guided model building.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@poietic-mcp Model the fishing economy from Thinking in Systems and simulate 200 years."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
poietic-mcp
An MCP server that lets an agent read, edit, validate and simulate Poietic Stock and Flow designs, alongside a human working in Poietic Playground.
The design file is the integration point. The agent edits a .poietic file
through this server by driving the
poietic CLI; the human opens
or reloads the same file in the playground. Agent edits, human views and
direct-manipulates; both sides re-read.
Install
# 1. Build and install the poietic CLI (Swift 6.x, macOS 15+ or Linux)
git clone https://github.com/OpenPoiesis/poietic-tool
cd poietic-tool && git checkout v0.9 && ./install # installs to ~/.swiftpm/bin/poietic
# 2. Build this server
git clone https://github.com/soobrosa/poietic-mcp
cd poietic-mcp && npm install && npm run buildRelated MCP server: a0
Configure
The server works with any MCP client. The command to register is always:
node <absolute-path-to>/poietic-mcp/dist/index.jswith optional environment variables (see below). Environment:
POIETIC_MCP_WORKSPACE- allowlist root. Design paths and export outputs must live inside it. Defaults to the server's working directory. Set it to a dedicated designs folder (e.g.~/Documents/poietic-designs) for a tight fence, or your home directory to work with designs anywhere.POIETIC_BIN- path to thepoieticbinary. Defaults to~/.swiftpm/bin/poietic.POIETIC_DESIGN- optional default design path, used when no current design is set.
Claude Code
claude mcp add --scope user poietic \
--env POIETIC_MCP_WORKSPACE=$HOME \
--env POIETIC_BIN=$HOME/.swiftpm/bin/poietic \
-- /opt/homebrew/bin/node /absolute/path/to/poietic-mcp/dist/index.jsVerify with claude mcp list (should show poietic: ... - ✔ Connected) or
/mcp inside a session. --scope user makes it available in all projects;
use --scope project to register it only for one repository (writes to that
repo's .mcp.json).
Claude Desktop
Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json
(create the mcpServers key if absent), then fully quit and reopen the
app (Cmd+Q; MCP servers only start at launch):
{
"mcpServers": {
"poietic": {
"command": "/opt/homebrew/bin/node",
"args": ["/absolute/path/to/poietic-mcp/dist/index.js"],
"env": {
"POIETIC_MCP_WORKSPACE": "/Users/you",
"POIETIC_BIN": "/Users/you/.swiftpm/bin/poietic"
}
}
}
}The poietic tools appear under the tools icon in a chat.
Factory Droid / other clients
Register the same command in the client's MCP settings (e.g. .mcp.json in
the workspace for Droid, project config for other clients):
{
"mcpServers": {
"poietic": {
"command": "node",
"args": ["/absolute/path/to/poietic-mcp/dist/index.js"],
"env": {
"POIETIC_MCP_WORKSPACE": "/Users/you/Documents/poietic-designs",
"POIETIC_BIN": "/Users/you/.swiftpm/bin/poietic"
}
}
}
}Verifying the setup
From a terminal, drive the server directly like an MCP client would:
node src/test/smoke.mjs # registers, builds a tiny model, simulatesUsing it
You do not invoke tools by name; you talk, and the agent picks the
poietic_* tools as the conversation turns to building models.
A typical build request:
Create a new Poietic design called fishing.poietic in ~/Documents/poietic-designs and model the fishing economy from Thinking in Systems: a fleet (capital) that grows 5% per year, fish that regenerate as a function of fish density, harvest yield falling as fish get scarce, price rising as fish get scarce. Validate and simulate 200 years.
A typical inspect-and-modify request:
Open Capital.poietic in ~/Downloads/_Converted/ThinkingInSystems, show me the structure, then double the initial resource and re-run the simulation.
Working alongside Poietic Playground: open the same design file in the
playground to see and edit the agent's work by hand. After saving in the
playground, the agent's next write is refused with a fingerprint conflict;
tell it to re-read the design (poietic_get_design) and continue. See
PLAYGROUND.md for the handoff protocol.
The guided recipe: ask the agent to use the build_stock_and_flow_model
prompt for a description of a system. It encodes node roles (Stock vs
FlowRate vs Auxiliary), Flow vs Parameter edge semantics, formula syntax, and
the validate-then-run ordering - including two lessons learned the hard way:
Node names can contain spaces. In formulas, wrap those names in curly braces, for example
{account balance} * {interest rate}. Name matching is case-insensitive, and spaces and underscores normalize to the same name.poietic_auto_parametersdoes not wire Parameter edges into or out of GraphicalFunction nodes. After auto-parameters, validate; for each issue, connect the missing edge explicitly and re-validate.A stated growth-rate goal is usually a net rate. An investment goal of g% of the stock with d% depreciation yields net growth of (g - d)%; setting g = d freezes the stock. Gross goal = depreciation + desired growth.
Tips:
Mention the design's folder so the agent stays inside the workspace fence.
Ask for
poietic_validatebefore simulating; the agent will usually do it unprompted, but a broken model fails inpoietic_runwith the same issues.Ask for results as summaries, not raw dumps -
poietic_runalready returns a per-variable summary with capped sample rows, and can write the full CSV to a file if you give it anoutputPath.
Tools
Session: poietic_use_design binds the current design (and snapshots a
content-hash fingerprint as the session baseline); every other tool takes an
optional design override.
Tool | Purpose |
| Metamodel as markdown (cached). Schema discovery. |
| Normalized design JSON: |
|
|
| Create an empty design; becomes current. |
| Create a node; returns |
| Create an edge, optionally with v0.9 attributes; returns |
| Set attributes; one undo entry (single transaction on poietic-tool v0.8+). |
| Remove stored attribute values in one transaction (v0.9+). |
| Remove a node or edge (cascades edges). |
| Wire required parameter edges, drop unused ones. |
| One tool call = one transaction. |
|
|
| Simulate with |
| SVG diagram export. |
| Graphviz DOT (stdout if no path). |
| Plane exchange between design files. |
Resources: poietic://metamodel, poietic://builtins (formula operators,
functions and variables; poietic-tool v0.8+), poietic://design/current,
poietic://design/current/diagram.svg.
For a v0.9 Simulation settings object, use start_time, time_step, and
final_time (replacing initial_time, time_delta, and end_time).
solver_type accepts euler or the fixed rk4 solver. flow_scaling
accepts outflow_first or inflow_first; set it when competing flows may
exceed available stock. The steps run option is deprecated, so prefer
finalTime.
Prompt: build_stock_and_flow_model - encodes node roles, Flow vs Parameter
edge semantics, formula syntax, and the validate-then-run ordering.
Safety model
Argv only. The CLI is spawned with an argv array; formulas containing
*, spaces or parentheses are never interpreted by a shell.Per-design mutex. Every CLI invocation is a whole-file read-modify-write; concurrent calls are serialized per design.
Fingerprint guard. After the first bind, any external change to the design file (e.g. the human saving in the playground) blocks writes with a clear error until the agent re-reads the design. Conflicts are detected, never merged.
Path allowlist. Designs and outputs must be inside
POIETIC_MCP_WORKSPACE.Verbatim errors. Non-zero CLI exits surface the CLI's stderr unchanged.
No silent nulls. A create whose output cannot be parsed for the new object ID is a hard error.
Development
npm run build # tsc
npm test # parser fixtures + integration (needs the poietic binary)
node src/test/smoke.mjs # drives the built server over stdio
node src/test/from-description.mjs # builds a model from prose onlyfixtures/raw/ holds recorded stdout/stderr from the real CLI (see
fixtures/FINDINGS.md for observed behavior and deviations from the docs);
fixtures/capture.sh reproduces them. src/test/capital.test.mjs rebuilds
the Thinking in Systems Capital model through the MCP tools and asserts the
rebuilt simulation reproduces the committed original variable by variable.
Troubleshooting
poietic binary not found- build and install poietic-tool, or pointPOIETIC_BINat the binary.Path is outside the allowed workspace- the design path is not underPOIETIC_MCP_WORKSPACE; move the file, or update the server's env in the client config (restart the client afterwards).The design changed outside this session- the file was saved externally (playground, another agent). Re-read it withpoietic_get_design, then retry the write.Validation issues about graphical functions - run
poietic_auto_parameters, then connect the missing GraphicalFunction edges explicitly (see the from-prose lessons under "Using it").Claude Desktop shows no poietic tools - the app loads MCP servers only at launch; quit fully (Cmd+Q) and reopen. Logs:
~/Library/Logs/Claude/mcp*.log.
Known limitations
No live playground drive. The human reopens the file; the playground has no reload-on-change.
Concurrent editing is detected, not merged. The fingerprint guard refuses the write; re-read and re-apply.
Multi-step agent edits are not atomic. Each tool call is one transaction; one
undoreverses one call. (poietic_set_attributeswith several attributes is a single transaction on poietic-tool v0.8+; older builds create one entry per attribute.)Duplicate object names resolve arbitrarily upstream, so name-based references are only safe when uniqueness is known. Prefer numeric IDs.
Available Tools
18 toolspoietic_add_nodeAdd Poietic nodeA
Create a new node (e.g. type Stock, FlowRate, or Auxiliary) with attributes. Typical attributes: name (string, required), formula (string, required - a constant like "100" or an expression like "account * rate"), position ([x, y]). Returns {objectId, planeId}. Thread the returned objectId into later calls; duplicate names resolve arbitrarily upstream, so prefer IDs.
Inputs: type (required), design, attributes.
poietic_arrangeArrange Poietic objectsA
Arrange nodes on the canvas. mode 'circle' lays out all (or the given) nodes in a circle; align modes (left, center-horizontal, right, top, center-vertical, bottom, offset-horizontal, offset-vertical, spread-horizontal, spread-vertical) align the given nodes.
Inputs: mode (required), refs, design, spacing.
poietic_auto_parametersAuto-connect Poietic parametersA
Automatically wire Parameter edges: connect required parameter edges for every formula variable, and disconnect unused parameter edges. Stock and Flow models stay consistent only if every formula parameter is wired and no stale parameter edges remain - run this after editing formulas and connections. Returns the created and removed edge IDs.
Inputs: design.
poietic_connectConnect Poietic nodesA
Create an edge between two nodes. Edge types: Flow (between a FlowRate and a Stock; direction is flow direction) and Parameter (from a value node to the node whose formula uses it). NOTE: edge attributes cannot be set at creation; use poietic_set_attributes afterwards if needed. Returns {edgeId}.
Inputs: type (required), origin (required), target (required), design.
poietic_export_planeExport Poietic planeA
Export the current (or given) plane as a poietic design file for later import.
Inputs: outputPath (required), plane, design.
poietic_export_svgExport design as SVGA
Export the current plane as an SVG diagram. Note: pictograms require a pictogram collection file (from the Diagramming package); without it the diagram renders with plain shapes.
Inputs: outputPath (required), zoom, plane, design, +2 more.
poietic_get_designGet Poietic designA
Read the current Poietic design as normalized JSON: {formatVersion, metamodel, planeId, undoDepth, redoDepth, nodes[], edges[], unstructured[]}. Each node is {id, type, name, attributes}; each edge is {id, type, origin, target, attributes}. Replaces list and show. Prefer numeric IDs over names for references (duplicate names resolve arbitrarily upstream).
Inputs: design.
poietic_import_planeImport Poietic planeA
Import a plane from another poietic design file into the current design. identity mode: 'require' (default; object IDs must match), 'auto', or 'new' (re-identify objects).
Inputs: file (required), plane, design, identity.
poietic_metamodelPoietic metamodelA
Describe the Poietic metamodel (object types, traits, attributes, edge types) as markdown. Pass a type name (e.g. Stock, FlowRate, Auxiliary, Flow, Parameter) for a single type, or omit it for all types. This is the schema-discovery path: check attribute names and types here before setting attributes.
Inputs: type.
poietic_new_designNew Poietic designA
Create a new empty Stock and Flow design at the given path and make it the current design. Optionally import one or more poietic planes into the first plane.
Inputs: path (required), import.
poietic_redoRedo Poietic editA
Redo the last undone edit transaction on the design.
Inputs: design.
poietic_removeRemove Poietic objectA
Remove an object (node or edge) by ID (preferred) or unique name. Removing a node also removes its connected edges (the CLI reports 'Removed cascading').
Inputs: ref (required), design.
poietic_runRun Poietic simulationA
Run the Stock and Flow simulation and return a per-variable summary (initial, final, min, max) plus capped sample rows of the CSV output. Use 'variables' to observe specific nodes (names or IDs); with no 'variables', output contains time plus all object variables (poietic-tool v0.8+; use 'allVariables' to also include internal/built-in variables). Use 'parameters' to override node values for the run: stocks get a new initial value, other nodes are affected only at t=0 and then recomputed from their formulas. Pass 'outputPath' to also save the full CSV (inside the workspace). Validate the design first: a model with formula errors fails here.
Inputs: plane, steps, design, solver, +7 more.
poietic_set_attributesSet Poietic attributesA
Set one or more attributes on an object (node or edge), referenced by ID (preferred) or unique name. On poietic-tool v0.8+ all attributes are applied in a single transaction (one undo history entry). On older builds each attribute is a separate CLI transaction (N entries); the response states which mode was used. To set an edge attribute, use the edge's numeric ID (edges have no names).
Inputs: ref (required), attributes (required), design.
poietic_undoUndo Poietic editA
Undo the last edit transaction on the design. Note: each edit tool call is one transaction, so one undo reverses one tool call (poietic_set_attributes with N attributes created N entries).
Inputs: design.
poietic_use_designUse Poietic designA
Set the current design file for subsequent tools. The path must be inside the configured workspace (POIETIC_MCP_WORKSPACE or the server's working directory). Snapshots the design's content hash as the session baseline: if it changes externally (e.g. saved in the playground), writes will be refused until you re-read the design.
Inputs: design (required).
poietic_validateValidate Poietic designA
Validate the design for errors (formula errors, unknown parameters). Returns {ok, issues[], summary} where each issue is {objectId, typeName, name, severity, message}. Run this after editing and before simulating.
Inputs: design.
poietic_write_dotWrite Graphviz DOTA
Write the design graph as a Graphviz DOT file (no pictogram dependency). Omit outputPath to receive the DOT source in the response.
Inputs: design, labels, outputPath.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool targets a distinct capability: schema discovery, design lifecycle, node/edge editing, validation, simulation, layout, and export/import. Even the export tools are clearly separated by output format, and the manual edge creation vs auto-wiring tools serve different workflow stages.
All tools share the poietic_ prefix and mostly use imperative/snake_case names (get_design, add_node, set_attributes, export_svg). A few names are verb-only (validate, connect, run) and poietic_metamodel is a noun-only outlier, so the pattern is not perfectly uniform.
Eighteen tools is slightly above the typical comfortable range, but each maps to a needed operation across model editing, simulation, and exchange. The count feels justified rather than bloated for a domain with both editing and simulation/export workflows.
The set covers schema discovery, design creation/loading/reading, node and edge CRUD-style operations, attribute updates, validation, undo/redo, simulation, layout, and multiple export/import paths. There are no obvious dead ends for a stock-and-flow modeling workflow.
Maintenance
Related MCP Connectors
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Deterministic reasoning stack for AI agents: simulate, decide & compute, plus cross-domain tools.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to load, simulate, inspect, and edit EPANET hydraulic/water-quality models locally via stdio.33MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to open, edit, check, run, emit, and save source programs through structured, revision-checked tools over stdio, confining paths to the launch root and returning diagnostics with fixes for rejected edits.2Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables agents to build, validate, calibrate, and export versioned scientific models with mandatory units, dimensional and numerical checks, and uncertainty analysis over stdio. Models can be simulated and exported to portable formats such as SBML, CellML, and Modelica.27 npm9MIT
- FlicenseNot gradedqualityAmaintenanceEnables LLMs to interact with Python environments, run code and scripts, manage packages, and read or write files within a configured working directory.-