Using FlowState with AI agents (MCP)

FlowState includes a Model Context Protocol (MCP) server. MCP is the open standard that AI assistants such as Claude Desktop and Claude Code use to call tools. With it, an assistant can read and change variables, run the simulation, read key results and problems, and run sensitivity sweeps and Monte Carlo studies.

The server is part of flowstate-cli:

flowstate-cli mcp [FILE]                       work on a .flow file
flowstate-cli mcp --connect http://127.0.0.1:8765   work on the document open in the desktop app
flowstate-cli mcp --connect … --edits direct        apply the assistant's edits without review

It talks to the assistant over standard input and output. It does not open a network port.

Two ways to work

On a file. flowstate-cli mcp my-process.flow loads the file into memory. The assistant’s edits stay in memory until it calls save_project. Without a file, the server starts with the built-in Getting Started sample.

On the desktop app. In FlowState, choose Tools ▸ Start automation server. Then start the MCP server with --connect http://127.0.0.1:8765. The assistant now works on the document in your window:

the assistant’s edits are proposed for your review first (see Reviewing proposed changes); nothing changes until you accept;
each accepted set of changes is one undo step, so Ctrl+Z undoes it;
before open_project replaces the document, the app asks you about unsaved changes.

To let the assistant change the document directly, as in earlier versions, start it with --edits direct. Then each change appears on screen straight away and is one undo step.

Tools

Tool	What it does	Changes things?
`status`	Which document is open, its file and revision	No
`list_vars`	Variable paths, filtered by `prefix` and `search` words	No
`get_var`	Read one input, or a `results/…` value	No
`set_var`, `set_vars`	Change one or several inputs. Values are checked first, and a batch is all or nothing. In review mode they are proposed instead	Yes, undoable (review mode: after you accept)
`rename`	Rename a procedure, operation, equipment tag, stream or auxiliary equipment and update every reference to it	Yes, undoable (review mode: after you accept)
`replace`	Point every use of a component, mixture, consumable, agent or labour category at another registered one, or replace the power type	Yes, undoable (review mode: after you accept)
`propose_changes`	Propose edits, each with an optional rationale, for you to accept or reject	Only after you accept
`get_changeset`	The pending proposals and their effect on the key figures	No
`simulate`	Run the balances, scheduling and economics, and return the key figures	No
`get_results`	Key figures and problems, plus streams, procedures, schedule, economics, environment or LCA	No
`list_procedures`, `get_procedure`	The unit procedures, then the inputs and results of one of them	No
`run_sweep`	Sweep one variable between two values	No (works on copies)
`run_monte_carlo`	Sample variables from uniform, normal or triangular distributions and return percentiles	No (works on copies)
`export_report`	HTML, Word or RTF report, batch sheet, or Excel workbook	Writes a file
`open_project`	Open a `.flow` file in place of the current document	Replaces the document
`save_project`	Save to the current file, or to a new `.flow` file	Overwrites a file

Each tool carries MCP annotations. Reading tools are marked readOnlyHint. open_project, save_project and export_report are marked destructiveHint, so clients that ask before destructive actions ask about these.

Variable paths are the same as in the command line and automation API, for example procedures/P-3/operations/FERMENT-1/duration/process, streams/Media/spec/Glucose, economics/tax_rate and results/economics/npv.

Reviewing proposed changes

With --connect, the MCP server runs in review mode by default. When the assistant calls set_var, set_vars or propose_changes, the edits are checked and added to a list of proposed changes. Your document does not change yet.

A message appears, and the status bar shows a badge such as ✦ 3 proposed. Click it, or choose Tools ▸ Review proposed changes… (also in the Ctrl+K palette).
The Proposed changes panel lists each edit as current → proposed value with its unit, who proposed it (mcp, api or assistant, and the session) and the assistant’s reason.
Below the list, a table shows how the ticked edits change the key figures: unit production cost, cycle time, batches per year, NPV, process mass intensity, CO₂e (when CO₂-eq factors are set) and the number of problems. FlowState works this out by solving a copy of your project in the background, so the window stays responsive.
Untick the edits you do not want and click Accept N selected. The ticked edits are applied as one undo step; the unticked ones are discarded. Reject all discards every proposal and leaves the document unchanged. Tools ▸ Accept all proposed changes and Reject all proposed changes do the same without opening the panel.

Accepted edits are recorded in the project’s provenance log, which is saved with the .flow file: the variable, the value, the source, the session and the time. In the Settings pane, a selection with such fields shows ✦ N field(s) set by AI; hover over it, or over a symbol in the Equations section, to see “set by AI (session …)” and when.

The same review workflow is available to any client of the automation API: POST /changeset/propose, GET /changeset, POST /changeset/accept and POST /changeset/reject (with {"indices": [0, 2]} to choose some edits). Working on a file (flowstate-cli mcp FILE) is always direct; there, propose_changes and get_changeset are useful to preview the effect of edits before making them.

Resources

The server also offers read-only resources:

flowstate://project: the whole document as .flow JSON;
flowstate://vars: every input and result path, one per line;
flowstate://results/summary: key figures and problems;
flowstate://docs/index: this user guide and the list of engine model notes.

Setting up Claude Desktop

Open Settings ▸ Developer ▸ Edit Config and add FlowState to claude_desktop_config.json. Use the full path to flowstate-cli:

{
  "mcpServers": {
    "flowstate": {
      "command": "C:\\Program Files\\FlowState\\flowstate-cli.exe",
      "args": ["mcp", "--connect", "http://127.0.0.1:8765"]
    }
  }
}

To work on a file instead, replace the arguments with ["mcp", "C:\\Projects\\my-process.flow"]. Restart Claude Desktop. FlowState then appears in the list of connectors.

Setting up Claude Code

Add the server from a terminal:

claude mcp add flowstate -- flowstate-cli mcp --connect http://127.0.0.1:8765

Or put a .mcp.json file in your project folder:

{
  "mcpServers": {
    "flowstate": {
      "command": "flowstate-cli",
      "args": ["mcp", "models/my-process.flow"]
    }
  }
}

Then ask, for example: “List the fermentation variables, raise the glucose feed by 10 %, simulate, and tell me how the unit production cost changes.”

Security

The automation API listens on 127.0.0.1 only. It refuses requests from other hosts and from web pages on other sites, unless you allow them under Tools ▸ Allowed web origins.
--connect accepts loopback addresses only.
Session token (optional). Set the environment variable FLOWSTATE_API_TOKEN before you start FlowState, or pass flowstate-cli serve --token …. Every request must then send that token. Give the MCP server the same token with --token …, or set the same variable in its environment ("env": {"FLOWSTATE_API_TOKEN": "…"} in the configuration above).
save_project and open_project accept .flow files only, and export_report writes only files whose extension matches the format.
An assistant can change your document. In the desktop app its edits wait for your review by default, and accepted changes can be undone, but keep a saved copy of important work.

Keyboard shortcuts

FlowState User Guide