Approve once. It runs on your canvas and checks its own work.
Two ways to let an AI drive Oreumics, both ending on the same node graph you can see, edit and reproduce. Inside the app, Approve & Run turns a plan into a verified, budgeted loop. Outside it, Claude Desktop, the ChatGPT desktop app and Claude Code connect over MCP and propose plans that arrive as the same Apply cards.
Plan → run → verify — and re-plan when a step falls short.
Every Action Plan card in the AI Chat carries two buttons. Apply stages the change and stops. Approve & Run hands the plan to the agent, which executes it on the visible canvas and treats each node’s result as evidence, not as a thumbnail to eyeball.
Plan
You describe a goal in the AI Chat. The model answers with an Action Plan card — nodes to add, parameters to set, which node to run.
Approve once
Press Approve & Run instead of Apply. The plan is registered with the backend as an agent run with a fixed budget.
Apply & run on the canvas
The plan is applied, then the created nodes and everything downstream run where you can see them — figures render in the app as usual.
Verify each step
Every finished node reports back. The backend checks the result structurally against what that node type must produce, plus any target the plan stated.
Re-plan on failure
A failed check sends the reason back into the chat as a new turn. The model states what it is changing and returns a corrected plan that re-runs the same node.
What “verified” checks
The baseline for every node is “completed, produced verifiable evidence, did not annihilate the data”. Node types with known outputs get a stricter rule. A plan may also state a target; missing it is reported as goal unmet and routed to tuning rather than counted as an error.
status == completedthe node finished — “no exception” is not enoughn_obs > 0the cells did not silently vanishpca → obsm["X_pca"]the embedding landed where downstream nodes look for itneighbors → uns["neighbors"]a graph exists before clustering asks for oneumap / tsne → obsm["X_umap" | "X_tsne"]coordinates exist before anything plots themclustering → n_clusters ≥ 2a partition, not one undifferentiated groupexpect: { n_clusters: "==8" }an optional target in the plan; “structurally fine but off-target” triggers tuning, not a pass
clustering produced 12 clusters; expected n_clusters == 8
update_paramsresolution1.00.6run_nodeIllustrative transcript. The wording of the continuation turn and the budget counters are the app’s; the numbers are an example.
The rails that make one approval safe
A finite budget
Per approval: 40 node operations, 2 attempts per failing step, 15 rounds, and 12 goal-seeking tuning iterations. The chat panel adds its own cap of 12 automatic re-plans. Wiring actions (connect / disconnect) do not consume steps.
Stop
A Stop button sits in the chat panel while a run is active, with the current step shown. The run is marked aborted and no further continuation is sent.
Undo
The canvas is snapshotted before the run. Undo restores it — nodes, edges and parameters — in one click, scoped to the workflow the run happened in.
Never off-screen
Execution is canvas-bound: there is no headless run path for the agent or for an MCP client. What runs is what you can see, click on and inspect.
Guided or Auto is a chip in the chat input. In Auto, plans apply and run without a click and the model plans whole pipelines; a plan that deletes a node or an edge still waits for an explicit Apply. Details on the AI Copilot page.
Use the assistant you already have — from a dialog inside the app.
Oreumics runs a Model Context Protocol server on your PC. Open Connect an AI assistant from the hub icon in the toolbar (or the AI Assistant menu) and pick a card. Each one is three steps, and the last step is the same everywhere: the dialog watches for the assistant’s first request and shows “connected · last activity 3 s ago” without you doing anything.
Claude Desktop
Recommended · install one file
- 1.Save extension file… writes the verified Oreumics extension (.mcpb) to a folder you pick — Downloads by default.
- 2.Drag the file onto the Claude Desktop window, or use Settings → Extensions → Advanced settings → Install Extension…
- 3.Check the connection: the dialog reports “connected” the moment Claude Desktop makes its first request.
The Microsoft Store edition of Claude Desktop registers no .mcpb file type, so double-clicking the file never worked — which is why the dialog saves it somewhere findable instead. No Node install, no JSON, no secret to copy: the bundled bridge reads the connection details Oreumics writes at startup. A config-file fallback (mcp-remote, needs Node.js) is under Advanced.
ChatGPT desktop app (Codex)
Also sets up Codex CLI and the IDE extension
- 1.Add to ChatGPT / Codex app writes an [mcp_servers.oreumics] entry — URL plus the secret header — into ~/.codex/config.toml, keeping a backup of the previous file.
- 2.Quit the app completely and open it again; it reads the file at startup.
- 3.Check the connection in the same dialog.
The app’s own “Add server” form cannot take a header, so the file is the only complete route. Codex CLI and the Codex IDE extension read the same file. ChatGPT on the web or on a phone cannot connect: it calls out from OpenAI’s cloud and cannot reach an app on your PC.
Claude Code
Terminal and IDE agent
- 1.Add to Claude Code writes mcpServers.oreumics (native HTTP plus the header) into ~/.claude.json.
- 2.Open a new terminal or restart the IDE.
- 3.Check the connection. Copy buttons for the claude mcp add command and a project-level .mcp.json are there too.
Older installs that registered the server under the previous “bioflow” key are migrated: the button removes the old entry while writing “oreumics”, so tools are not listed twice.
Illustrative. The dialog polls the backend every two seconds; the backend records which client made each request.
What a connected assistant gets
The same read tools
Every read tool the in-app chat has — data overview, markers, QC, spatial, provenance and the rest — resolved against the focused workflow, or any open one by workflow_id.
The node catalogue
list_nodes / describe_node return runnable nodes with their full parameter schema; list_ui_features keeps non-runnable workspaces such as Figure Canvas separate.
Session awareness
list_workflows reports the project, every open workflow, which one is focused, its revision and the current Guided / Auto default.
Reports
get_report_outline detects sections without a model call; generate_report writes a full HTML report to ~/.bioflow/reports/ using your key.
propose_canvas_plan — the only execution tool
Add, configure, connect, delete and run_node actions for the focused workflow, checked against its current revision. There is no headless run_node; a client that calls one is redirected here.
Proposals land in your chat as Apply cards
When an assistant calls propose_canvas_plan, the app injects the plan into the AI Chat tab as the same Apply / Undo card the in-app chat uses, focuses that tab, shows a snackbar and counts unapplied proposals on a red badge — so a plan is never missed while you are looking at Claude or ChatGPT. A stale revision, a non-focused workflow or an invalid parameter is rejected before anything is shown.
Guided or Auto, per request
“Walk me through it” gets a guided plan that waits for Apply, one step at a time. “Just run the whole thing” gets an auto plan that applies and runs immediately, Undo still available. When the assistant does not say, it uses the Mode chip in your chat panel. After a run it reads the real results back with the same tools and proposes the next step.
Your AnnData never leaves the PC.
Connecting an assistant moves no data. The assistant’s model runs wherever it runs; what crosses the wire are tool results — counts, names, summaries — with images stripped before they leave the process. What guards the door:
Loopback only
The server listens on 127.0.0.1. Nothing on your network can reach it; nothing is uploaded anywhere.
Two secrets, not one
The key an MCP client holds (X-Bioflow-Secret) opens only the /mcp endpoint. Every other route — data, projects, export, the canvas channel — needs a second credential the app regenerates at each launch and never hands out, not even to the chat panel’s renderer.
One execution policy, three surfaces
Whether an AI may run anything is decided in one place and shared by MCP, the in-app agent and the run-node endpoint. In the installed app it is on; BIOFLOW_MCP_ALLOW_EXEC=0 is the kill switch for a locked-down machine (developer builds default to off).
Also true
The extension file is verified byte-for-byte before the app offers it, and a release build fails rather than ship a stale one. The server speaks the 2026-07-28 revision of MCP alongside the 2025 ones, rejects batched requests and foreign origins, and strictly checks tool inputs — an argument Oreumics does not define gets an error, not silence.
We’ll tell you which is which.
In the download today
- Approve & Run — plan, apply, run, verify, re-plan; budget, Stop, Undo
- Guided / Auto execution modes, destructive actions always gated
- Claude Desktop via Save extension file… and drag-and-drop
- ChatGPT desktop app (Codex), Codex CLI and IDE extension via config.toml
- Claude Code via ~/.claude.json, plus copyable CLI / .mcp.json
- Live connection check in the dialog
- Provenance receipts on every run, RO-Crate in project export
Not possible · no timeline
- ChatGPT on the web or mobile — cloud-originated, cannot reach your PC
- Claude on the web or mobile — same reason
- Headless or unattended runs — every execution is on the visible canvas
Cloud clients would need a relay we have not built and have not committed to. Listed so you know why the dialog does not offer them.
Plans · Verifies · Reproduces
An agent that shows its receipts.
Every node the agent runs writes the same provenance receipt a manual run does — parameters, seed, package versions — and the chat can read it back. Free during the beta; access by request.