Edit a folder on your computer

You can keep a workspace in a folder on your own machine and edit it from the hosted website or from an AI assistant — without your projects ever leaving your computer. A small program called the Flowline helper runs on your machine and the website (or your assistant) talks to it over localhost.

After this chapter you can install the helper, run it over a folder, edit that folder straight from the website, and point an MCP assistant at it.

Your files stay put. The helper reads and writes the folder you choose on your computer. The hosted site only sends edits to the helper on your machine — it never stores your project bytes on the server.

Two different things. To let an AI assistant work on a folder, you need nothing but the one-line config in Edit with an AI assistant — no account, no token, no pairing. Pairing and the serve command below are only for editing a local folder in the website.

What you need

Node.js 20 or newer. Nothing else — the helper is a single self-contained download.

Get the helper

Download flowline-helper.tgz from your Flowline site.

Unpack it and enter the folder:

tar -xzf flowline-helper.tgz
cd flowline-mcp

Every command below is run from that flowline-mcp folder as node flowline-mcp.mjs <command>.

Start with a local editor only

If you only want to edit a folder on your own machine, you don't need to sign in anywhere.

Create a folder for your flows, then start the helper over it:
```
mkdir -p ./my-flows
node flowline-mcp.mjs serve --folder ./my-flows
```
The folder must already exist — serve reports an error if it can't find it.

You'll see Flowline helper serving ./my-flows on http://127.0.0.1:8788.
Open http://127.0.0.1:8788/ in your browser. You get the full editor, working directly on ./my-flows.

Leave the command running while you work. Stop it with Ctrl+C; start it again the same way to pick up where you left off.

Use it from the hosted website

This lets you open the website your team already uses, but keep a workspace's files on your computer. The first run pairs this computer with the site and starts serving your folder in one command.

Sign in to your hosted Flowline, for example https://flow.example.com. (Sign-in must be on — pairing is tied to your account.)
Serve a folder, pairing on the way:
```
node flowline-mcp.mjs serve --folder ./my-flows --site https://flow.example.com
```
The helper prints a short code and opens the site's /pair page in your default browser with the code already filled in. Click Connect this device while you're signed in. If nothing opens (headless machine, SSH session), copy the printed link into a browser yourself. Either way, the helper starts serving ./my-flows as soon as you confirm.

Run the same command again later and it skips pairing (you're already linked) and goes straight to serving.
Back on the website, open the Workspace picker. Under "On your machine" you'll see your computer and its folders. Click one to open it — you're editing the local folder through the website.

Can't reach the helper? Some browsers block a website from talking to localhost. If the picker shows "Couldn't reach the helper from this page," use the Open in local editor link it offers — the same http://127.0.0.1:8788/ editor as above. Make sure the serve command is still running.

Pairing separately. You can still run node flowline-mcp.mjs pair --site https://flow.example.com on its own — for example to re-pair with a different site before you're ready to serve a folder. serve --site calls the same flow automatically, so most people won't need this.

Edit with an AI assistant (MCP)

You can drive folders on this computer from an MCP assistant such as Claude Desktop, Cursor, or Copilot CLI. There is nothing to download and nothing to leave running — your assistant starts the helper itself.

Add one entry to your assistant's MCP config, listing the folders you want it to work on:

{
  "mcpServers": {
    "flowline": {
      "command": "npx",
      "args": ["-y", "flowline-mcp", "mcp", "/Users/you/my-flows"]
    }
  }
}

The folder path must not contain spaces — this is a known issue. flowline-mcp doesn't quote the path when your assistant restarts the connection, so D:\My Flows (or /Users/you/My Flows) will crash with 'C:\Program' is not recognized as an internal or external command on Windows. Use D:\MyFlows instead, or make a junction: mklink /J D:\MyFlows "D:\My Flows".

Restart your assistant and ask it to call list_workspaces — it will show one workspace per folder. Add more folders by appending them to args.

Your hosted workspaces too

To reach your hosted Flowline account from the same entry, add your site and a token from Connect MCP on the website — the panel there generates this whole combined snippet for you once you've entered both:

{
  "mcpServers": {
    "flowline": {
      "command": "npx",
      "args": ["-y", "flowline-mcp", "mcp", "/Users/you/my-flows"],
      "env": {
        "FLOWLINE_SITE": "https://flow.example.com",
        "FLOWLINE_TOKEN": "your-token"
      }
    }
  }
}

list_workspaces then returns both, each tagged local or hosted, with ids like local:abc and hosted:def. Point the assistant at one with select_workspace. If your token expires, the local folders keep working and the assistant will tell you the hosted side is unavailable.

For the full list of MCP tools and arguments, see Driving the tool with MCP and the MCP setup & reference.

Troubleshooting

"Your flowline-mcp helper is out of date." The site refuses a helper older than itself: helper and site must speak the same file API. Download the helper again (Get the helper) and restart serve. An assistant that reports This Flowline client is out of date needs the same update: change flowline-mcp to flowline-mcp@latest in its args and restart the assistant.
error: port 8788 is already in use. Another helper is running, or the port is taken. Start this one on a different port: node flowline-mcp.mjs serve --folder ./my-flows --port 8799 (open http://127.0.0.1:8799/ to match).
"Needs helper" next to your computer in the picker. The site can see your paired computer but the helper isn't running. Start serve and reload.
Running more than one helper. Give each its own settings with --config-dir <dir> so their pairings and ports don't collide.
Forgetting a computer. Use the ✕ next to a device in the picker. That only removes it from the list — your files are never touched.
On Windows, the MCP connection keeps dropping with 'C:\Program' is not recognized as an internal or external command. A space in the folder path you gave args — see the no-spaces note above.