flowgo — docs

Connect flowgo to Claude (MCP setup)

flowgo is an MCP server, so Claude — or any other MCP client — can draw a map for you and hand back a link you can open, drag around and keep editing. The hosted endpoint is one URL:

https://flowgo-map.com/api/mcp

There is no token to hunt for. flowgo needs no account, no API key and no OAuth dance — an anonymous session works immediately, and maps you share become public snapshot URLs. If you would rather have them saved to a flowgo account, see linking a session to your account below.

1. Claude Code

One command:

claude mcp add --transport http flowgo https://flowgo-map.com/api/mcp

Check it took with claude mcp list — flowgo should report Connected. To share the server with everyone working in a repository instead of adding it to your personal config, add --scope project; that writes the .mcp.json below. Remove it again with claude mcp remove flowgo.

2. Claude Desktop and claude.ai

A remote server like flowgo is added through the Connectors UI. (The claude_desktop_config.json file you may have seen elsewhere is documented for local stdio servers — it is not the path for a hosted URL.)

Open Settings — in the desktop app via the menu icon → File → Settings; in the browser via your profile icon → Settings.
Click Connectors in the sidebar.
Click Add, then Add custom connector.
Paste https://flowgo-map.com/api/mcp and confirm.
If you are offered Complete Authentication, you can skip it — flowgo has nothing to authenticate against.

3. A project-scoped `.mcp.json`

Drop this at the root of a repository and commit it, and everyone who opens that repository gets flowgo:

{
  "mcpServers": {
    "flowgo": {
      "type": "http",
      "url": "https://flowgo-map.com/api/mcp"
    }
  }
}

Claude Code asks you to approve a project-scoped server the first time you start it in that directory, so a checked-in file can't connect anything behind your back. Cursor, VS Code and Windsurf accept the same mcpServers object — check your editor's own docs for where it wants the file to live.

4. Or run it locally, against your own file

The CLI serves the same MCP contract against a .flowgo file on your disk. Nothing is uploaded, nothing is shared, and the map is a file you can keep in git — this is the path for work that shouldn't leave your machine.

$ flowgo mindmap.flowgo
flowgo editing mindmap.flowgo
  GUI: http://127.0.0.1:54042
  MCP: http://127.0.0.1:54042/mcp

Point your client at the MCP: line it prints:

claude mcp add --transport http flowgo-local http://127.0.0.1:54042/mcp

Two things to read off that output, not copy from here. The port is picked at startup, so it will not be 54042 for you. And the local mount is /mcp, while the hosted one is /api/mcp — they are not interchangeable. Aiming a client at /api/mcp on the local server quietly returns the editor's own HTML rather than an error, which looks like a broken client.

Local mode exposes the 18 editing tools. The four the hosted server adds (start_workspace, share, create_map, authenticate) exist to mint public URLs and to attach them to an account, which is moot when the map is already a file you own. Install from the releases page.

5. What to say once you're connected

You do not need to name the tools. Ask for a map the way you would ask a colleague:

“Map this out — how a request moves through our checkout, and drill into the payment step.”
“Whiteboard the options for the migration, one branch per approach.”
“Sketch the service architecture as a flowgo map and give me the link.”
“Read architecture.md and lay it out as a system map.”

What comes back is a URL, not a picture: a live canvas you can open, rearrange, nest into and send to someone else. Ask for another pass and the agent mints an updated link. Because every node can hold its own submap, “now expand the payment step” gives you a level deeper rather than a more crowded diagram — see flowgo vs Mermaid for where that does and doesn't pay off.

Optional: link a session to your flowgo account

By default an agent's maps are anonymous snapshots. Ask it to call the authenticate tool and it returns a single-use link; open that link in a browser where you are signed in to flowgo and approve it, and from then on everything that session shares is saved into your account. The link expires after ten minutes, and only you should open it — approving it is what grants the agent that access.

Open the editor

Visit /app (or hit Start a map on the homepage). Each browser session gets its own canvas; edits are saved to your session as you type. Click Share to mint a snapshot URL, Import .flowgo to replace the map from a file, or Export .flowgo to download the current state.

For agents — MCP endpoint

JSON-RPC 2.0 over HTTP, the streamable-HTTP transport, protocol version 2025-06-18. Point any MCP client at:

POST /api/mcp

See Connect flowgo to Claude above for the client-side setup. The hosted server advertises 22 tools and one resource (flowgo://about, the .flowgo format reference). The ones worth knowing by name:

create_map — one-shot: turn complete .flowgo text into a public share URL in a single call. No workspace/session bookkeeping — the tool to reach for when you already have (or can write) the whole map.
start_workspace — get a workspace_id for this session, for incremental editing instead.
add_box, add_edge, add_text, add_line, update_box, delete_box, delete_edge, get_state, set_state — operate on the workspace.
share — persist the workspace as a public snapshot. Returns { id, url }; hand the url to a human.

Workspaces are in-memory and idle out after an hour. Persistence happens only when share or create_map is called.

Run flowgo yourself

Single-file local mode is unchanged:

flowgo mindmap.flowgo

Releases: github.com/lassediercks/flowgo/releases.

flowgo, on the public internet