FLUJO: a local-first MCP hub and visual agent builder for your own machine

The problem FLUJO addresses: MCP servers, keys and runtimes scattered across tools

If you use more than one MCP client, you already know the pattern. Claude Desktop has its own server list, Cursor has another, Cline has a third, and each one wants its own copy of the same GitHub token. Python-based servers need uv, Node-based servers need npx, and every client has a slightly different idea of where those live. FLUJO's answer is to be the place where you configure a server once. The README describes it as an MCP hub and inspector: you connect apps, and the same configuration can be re-exposed to other MCP clients (Claude Desktop, Cursor, Cline) over Streamable HTTP. That is the pitch, and it is a real one for anyone who has hand-edited three JSON config files to point at the same server.

The second problem is the one the README leads with: keys and data under your control. FLUJO is local-first by default, binds to localhost, encrypts secrets at rest in local storage, and keeps them server-side so the frontend only sees a masked placeholder. Whether that matters to you depends on whether you were comfortable pasting an Anthropic key into a hosted agent builder. FLUJO also supports local models through Ollama, so a fully offline-ish setup is on the table if your machine can run the model.

The audience is narrower than the README's marketing suggests. This is for someone who is willing to run a Node application, install toolchains, and read a compose file with a security warning in it. It is not a hosted service and the repository does not present it as one.

How FLUJO works: Next.js frontend, MCP workspaces, and PocketFlow graphs

The repository layout tells you most of the architecture. FLUJO is a Next.js application (next.config.mjs, tsconfig.json, a src/ tree) with a monorepo workspace list in package.json that includes five MCP packages: mcp-servers/bash, mcp-servers/browser, mcp-servers/filesystem, mcp-servers/flujo and mcp-servers/shared. Those are built first by the build script, before Next.js runs, which means the bundled servers are compiled artifacts rather than something fetched at runtime. The Dockerfile calls them "immutable offline built-ins" and explicitly notes that the volume mounts do not hide /app/mcp-servers.

Agent execution is a graph. The README says FLUJO is powered by the PocketFlow Framework, and the builder exposes Start, AI, connected-app, subflow and Finish nodes. Branching works by connecting one node to several successors and telling the model when to use each handoff tool from the Agent Tools tab; loops are made by connecting a node back to a previous one. A Subflow node runs another flow as a single step with its own isolated state, which is the closest thing here to calling a function. Per-node scoping decides which tools, resources and system-prompt fragments a node can see, so a subflow does not inherit everything its parent had.

On the client side, the Talk page runs a conversation against a selected agent and shows a live execution view with token usage and a context-window meter. The visual debugger sets breakpoints and steps through a run node by node, inspecting state before and after each step. Human-in-the-loop tool approval is optional and works across providers, including Claude Subscription's agentic tool use.

Installing FLUJO on Windows, Linux or macOS, and running a first agent

The README calls the installer the recommended path because it sets up everything FLUJO needs: Git, Node.js, Python, uv and ripgrep, then clones, builds and creates a global flujo command. On Windows there is a flujo-setup.exe download, or a PowerShell one-liner. On Linux and macOS it is a curl pipe:

curl -fsSL https://raw.githubusercontent.com/mario-andreschak/FLUJO/main/scripts/install.sh | bash

That script is the reason the README says MCP servers get all their runtimes: a bare Node install will not have uv or ripgrep, and some servers need them. If you already have Node.js, the README offers a shortcut that skips installation entirely:

npx flujo-ai

The README is explicit that this is the fastest start but that MCP servers may still need git, python or uv on your PATH. Note the engine requirement in package.json: node >=22.0.0. Below that, expect the build to refuse.

For Docker, the compose file documents a single command, `docker compose up`, and binds two ports to localhost only: 4200 for the app and 4201 for the MCP Apps transport used by isolated `<originKey>.localhost` browser origins. The compose file also warns in a comment that you should not change the binding to 4200:4200 unless FLUJO sits behind your own authenticating reverse proxy, because the git API executes frontend-supplied commands.

Once it is running, the first real use is the three-step server form the README describes: define the server, install and build it, then define how to run it, with a one-click connection test before saving. After that, the detail view lets you browse and call the server's tools, resources and prompts directly, which is the inspection half of the hub. Only then is it worth opening the Agent Builder and wiring a Start node to an AI node and a connected-app node. The README's own ordering (connect, then build, then talk) matches that sequence.

Where FLUJO is the wrong tool: no auth layer and a Node 22 floor

The most important limitation is stated by the project itself, in the docker-compose.yml header: "FLUJO has no authentication layer, and its git API executes frontend-supplied commands (RCE-equivalent)." That is why the port is bound to 127.0.0.1 by default and why the file tells you not to widen it. If your plan is to run FLUJO on a shared box and let a team reach it, you are on your own for the authenticating reverse proxy, and the project does not claim to provide one. A hosted, multi-user deployment is not what this is.

The second constraint is the toolchain. Node 22 or newer is mandatory. The Dockerfile deliberately avoids Alpine because onnxruntime-node, an optional transitive dependency, ships no musl builds and several MCP servers assume glibc; if your infrastructure standardises on Alpine base images, you will be fighting that. The runtime image also carries git, python3, uv/uvx and Node specifically so MCP servers can be installed on demand, which means the image is not small and the container has a writable HOME for npm's cache.

Third, the npx route and the installer route are not equivalent. The README says so plainly. If you pick `npx flujo-ai` to avoid a long install, you inherit responsibility for git, python and uv yourself, and servers that need them will fail at install time rather than at startup.

Finally, the README does not document rollback or downgrade for the workspace layout. The compose file mentions that two volume names are intentionally reused "so upgrading an existing Compose install exposes its old DB and MCP clones directly in the migrated layout", and the Dockerfile carries io.flujo.workspace.layout="2" and io.flujo.snapshot.format="2" labels, which implies a versioned on-disk format. What happens if you need to go back a layout version is not described in the README or the compose file.

FLUJO compared with wiring MCP servers into each client by hand

The realistic alternative is not another product. It is doing what most people do now: edit the MCP config file of each client separately, keep a shell script that starts Python servers with uvx, and accept that Claude Desktop and Cursor each have their own copy of the same token. That approach has real advantages. There is nothing extra running, no Next.js server on port 4200, no workspace database, and no layout migration to think about when you upgrade. If you use one MCP client and two servers, hand-editing is less work than installing FLUJO, and it will not break when FLUJO's workspace format changes.

The difference in approach is where the configuration lives and who owns the runtime. With hand-editing, each client owns its own server processes and its own secrets. With FLUJO, the configuration lives in FLUJO's encrypted workspace, FLUJO starts the servers, and other clients connect to FLUJO over Streamable HTTP to reach them. That is a genuine trade: you gain one place to define a server, one place to inspect its tools, and the ability to reuse it across clients; you lose the simplicity of a process that only exists while a client is open, and you add an application that must be running for the proxy to work.

There is also a scope difference. Hand-edited configs give you servers; they do not give you a visual graph builder, a step debugger, or a context-window meter. If you want those, you are choosing between FLUJO and writing your own orchestration code against the model APIs. FLUJO's answer is the PocketFlow-based node graph, with branching via handoff tools and subflows with isolated state. Whether a visual graph beats a Python file is a matter of how much you value seeing the state at each step.

Maintenance, release cadence and what the MIT licence means here

The repository is not archived, and the last push was on 2026-08-11, which is recent enough that the project is being worked on. The release list shows v3.45.0 on 2026-08-11, v3.44.0 on 2026-08-10 and v3.43.0 on 2026-08-08, so releases arrive in close succession. package.json lists version 3.45.2, slightly ahead of the most recent tagged release in the list. Frequent version bumps mean upgrade cost is not zero: you should expect to re-run the build or pull a new image regularly, and the workspace layout labels in the Dockerfile suggest the on-disk format is versioned and can change between releases.

The licence is MIT. That is permissive: you can use, modify and redistribute the code, including in commercial settings, provided you keep the copyright notice and licence text. It says nothing about the MCP servers you connect, which carry their own licences, and nothing about the model providers whose terms you accept when you add an API key or use a Claude Pro/Max subscription through the Claude Agent SDK. Those are separate agreements and this article is not legal advice.

One practical maintenance note from the README: the author asks for issues on GitHub or in Discord and says they read every message, aiming to respond within a day. That is a stated intention, not a guarantee, and it is the kind of thing you should weigh against your own tolerance for waiting on a fix.

Editorial conclusion

Adopt FLUJO if you want an MCP hub and a visual agent builder on a machine you control, and you can live with a Node 22 toolchain and a Docker port bound to 127.0.0.1. Do not adopt it as a multi-tenant service: the compose file states there is no authentication layer and that the git API executes frontend-supplied commands. Before you commit, verify that Node is at least 22.0.0, check whether your MCP servers need git, python3 or uv on PATH (the npm route does not install them), and read the Dockerfile's note that Alpine is avoided because onnxruntime-node has no musl builds.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes