Connect an AI assistant.

If you already work in Claude Desktop, the ChatGPT desktop app or Claude Code, you can drive Oreumics from there. The assistant becomes a remote control: it reads your analysis and proposes steps, and everything it does still happens on your canvas, on your machine.

Which assistants, and which cannot

Assistant	How it connects
Claude Desktop (recommended)	An Oreumics extension file (.mcpb) you save and drop onto the Claude Desktop window.
ChatGPT desktop app (Codex)	Oreumics writes one entry into the app’s config.toml. Codex CLI and the Codex IDE extension read the same file.
Claude Code	Oreumics writes a user-level entry into ~/.claude.json, available in every project.
ChatGPT on the web or phone	Cannot connect. Those clients call out from the cloud and cannot reach an app running on your PC.

Open the dialog

Click the hub icon in the top-right of the toolbar, or use the app menu AI Assistant → Connect an AI assistant (Claude / ChatGPT)… (the menu bar is hidden by default; press Alt to show it). The dialog asks which assistant you use and then shows a three-step guide for it. The status line at the bottom reads Oreumics is listening at … once the analysis engine is up; if it says the engine is still starting, wait a moment — it updates by itself.

Claude Desktop

01
Save the extension file somewhere easy to find
Press Save extension file… and keep the suggested Downloads folder. The bundled copy lives in a hidden AppData folder that Claude’s file picker cannot reach, which is why this step exists. Show saved file reveals it in Explorer.
02
Install it in Claude Desktop
Drag the saved .mcpb file onto the Claude Desktop window and click Install. Or open Settings → Extensions → Advanced settings → Install Extension… and pick the file. Open Claude Desktop launches the app for you.
03
Check the connection
Ask Claude something like “What data is loaded in Oreumics?”. The dialog watches for the first real request and switches to Claude Desktop is connected · last activity … by itself. Keep Oreumics open while you chat; no reinstall is needed after Oreumics updates.

Do not double-click the file

The Microsoft Store edition of Claude Desktop does not register the .mcpb file type on Windows, so double-clicking opens a text editor or an “Open with” prompt. Drag and drop, or Install Extension…, is the real path. If an editor window appeared, just close it.

Advanced: the collapsed section can instead write an oreumics entry into claude_desktop_config.json that runs npx mcp-remote. It needs Node.js on the PC and is only for when the extension cannot be installed.

ChatGPT desktop app (Codex)

01
Add Oreumics to the app
Press Add to ChatGPT / Codex app. Oreumics writes a [mcp_servers.oreumics] table with the server URL and its security header into ~/.codex/config.toml, keeping the previous file next to it as a backup. The app’s own Settings → MCP servers → Add server form cannot take the header, so the file is the reliable route; Do it by hand copies the block if you prefer.
02
Restart the app
The app reads the file when it starts. Quit it completely — not just close the window — then open it again.
03
Check the connection
Start a chat and ask about your Oreumics data; the dialog confirms the connection when the first request arrives.

Claude Code

01
Add Oreumics to Claude Code
Press Add to Claude Code. It upserts a user-level oreumics server into ~/.claude.json. Copy buttons give you the equivalent terminal command or a .mcp.json block for a single project instead.
02
Restart Claude Code
Open a new terminal (or restart the IDE) and run /mcp — oreumics should be listed as connected.
03
Check the connection
Ask Claude Code about your Oreumics data.

What the assistant can do once connected

Read — the node catalogue and each node’s parameters, the open workflows and which one is focused, and the same result tools the in-app Copilot uses (data overview, markers, QC, spatial and trajectory summaries, DE and DMP tables, installed resources, and more).
Propose — a canvas plan (create and connect nodes, change parameters, run) that arrives in the AI Chat tab as the same Apply / Undo card the Copilot produces. The tab opens itself, a snackbar appears and the tab shows a badge with the number of waiting proposals, so you do not miss it while looking at the other app.
Guided or Auto — say “run the whole pipeline” for a single auto-applied plan, or “one step at a time” to review each; unspecified, the app’s Mode chip decides. Plans that delete nodes or disconnect edges always wait for an explicit Apply.
Report back — after Apply, the assistant receives the real outcome (which nodes were created, whether the run completed, any errors) rather than a fire-and-forget acknowledgement, so it does not recreate nodes that already exist.

Enabling execution

Installed builds have execution on: the assistant can propose plans that create and run nodes. If the status line at the bottom of the dialog ends with running nodes from an assistant is off in this build, the assistant can only read and will tell you it has no tool to create nodes. That is the default when Oreumics is run from source; set BIOFLOW_MCP_ALLOW_EXEC=1 before starting it, then reconnect the assistant (toggle the extension off and on, or restart the client) so it picks up the execution tools.

Privacy and security

The MCP server listens on 127.0.0.1 only and is protected by a secret generated per install; the dialog handles that secret for you and never shows it on screen. The key an assistant holds opens only the assistant endpoint — your data, projects and exports need a second credential the app issues to itself at every launch and never hands out.

Raw matrices are never uploaded. But the summaries a read tool returns to an external assistant are processed by that assistant’s provider, so check the client’s own policy before pointing it at sensitive data.

Troubleshooting

The menu bar is not visible: It is hidden by default. Press Alt, or use the hub icon in the toolbar.
Double-clicking the .mcpb opened an editor: Expected on the Store edition of Claude Desktop. Close it and drag the file onto the Claude Desktop window, or use Install Extension… in Settings → Extensions → Advanced settings.
Both bioflow and oreumics tools appear: An old registration from before the rename is still present. Press Rename the old entry to Oreumics in the dialog; if you edited a file by hand, remove the old mcpServers.bioflow or [mcp_servers.bioflow] block.
The assistant says it has no tool to create nodes: Execution is off — see Enabling execution — or the client has not reconnected since it was switched on.
The assistant proposed something but nothing popped up: Proposals are not pop-ups. Open the AI Chat tab in the bottom panel; it shows a badge with the number of waiting plans.
“Oreumics has not published its connection details”: Restart Oreumics; the connection file the extension reads is written at startup.
The assistant keeps describing an old workflow: Fixed in v0.23.0 — update Oreumics. Reloading the app used to make the backend reject every later update, leaving the assistant on a stale snapshot.
A changed setting is not picked up: Backend-side changes (execution on / off) need an app restart; external clients need to reconnect to receive new tools and descriptions.