flowpad-mcp

Flowpad's MCP integration comes as two servers for two different jobs. This repo is the second one:

| | B — Hosted connector (main) | A — Local validator (this repo / npm package) | | ------------------------ | ------------------------------------ | ------------------------------------------------------ | | Where it runs | Flowpad's servers | your machine, via npx flowpad-mcp | | Transport | Streamable HTTP at a URL | stdio | | Auth | OAuth sign-in (or an fp_live_ key) | none — keyless | | Canvas read/write (CRUD) | ✅ yes | ❌ never | | Talks to Flowpad's API | ✅ (per-user, authed) | ❌ (except one anonymous version check) | | Tools | full toolset | describe_engine, validate_design, preview_layout |

Connect Claude to the hosted connector to actually read and edit your canvas (Flowpad → Settings → Integrations). The local validator is an optional enhancer you add alongside it: it carries Flowpad's real layout engine (flowpad-core) on your machine so the AI can validate and preview a design locally — instantly, free, offline — before it writes anything through the connector. Fewer wrong edits, fewer round-trips.

                 ┌─ A: npx flowpad-mcp (local) ── flowpad-core engine, on your machine
Claude / Cursor ─┤        validate · preview · describe   (keyless, no canvas access)
                 └─ B: hosted URL connector ──HTTP──▶ Flowpad API (auth + canvas CRUD)

A — the local validator (this package)

Keyless. It never touches your account; it only runs the engine locally. Add it next to the hosted connector in your MCP host:

Claude Desktop — claude_desktop_config.json / Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "flowpad-local": {
      "command": "npx",
      "args": ["-y", "flowpad-mcp@latest"]
    }
  }
}

Claude Code (CLI)

claude mcp add flowpad-local -- npx -y flowpad-mcp@latest

Google Antigravity — mcp_config.json

In Antigravity IDE or Antigravity 2.0, open Settings, look for "Open MCP Config", and add:

{
  "mcpServers": {
    "flowpad-local": {
      "command": "npx",
      "args": ["-y", "flowpad-mcp@latest"]
    }
  }
}

That's it — no key, no URL. (Advanced: set FLOWPAD_API_URL to point its best-effort "is my tool up to date?" check at a non-prod backend.)

Tools

| Tool | Purpose | | ----------------- | ------------------------------------------------------------------------------------------------------------------ | | describe_engine | The exact node types, layout values and limits to design within. | | validate_design | Run the SAME engine rules the backend enforces on a planned diff — catch a malformed node/edge before you send it. | | preview_layout | Compute where an auto-layout container's children land + flag overflow, before you write. |

All three run entirely on the bundled flowpad-core (no network), so a passing validate_design means the backend won't reject the shape.

Commands

Run in a terminal, not through the MCP host:

| Command | Purpose | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | npx flowpad-mcp login | Sign in once from this machine (browser + one Authorize click). Stores a token in your home directory; unlocks the canvas tools. | | npx flowpad-mcp sync-cache | Regenerate dev/flowpad/tasks-cache.md — a generated, read-only summary of the linked project's tasks, so tooling can grep the backlog offline. |

sync-cache needs the repo to be linked to a project (npx flowpad link <projectId>, from the flowpad package, which writes dev/flowpad/project.json). It compares the revision in the file's header with the project's current revision and rewrites only when they differ — --check reports without writing (exit 1 when stale), --force regenerates regardless. Signed out or offline it leaves the file alone and says it could not verify it.

You rarely have to run it. The connector refreshes that file itself: once when it starts, and at most every few minutes while it is in use. That is deliberate — the file is a photograph an agent orients from, a stale one sends it at tasks that were renamed or closed days ago, and the person who would notice is the last person who would think to run a command. The refresh is a comparison, so the usual case costs one small request and writes nothing; it never blocks a tool call; and when it cannot check (signed out, offline) it says so on the next tool result instead of leaving the agent to trust an old file. It does nothing at all in a directory that is not linked to a project.

Each attempt also leaves dev/flowpad/.tasks-cache-sync — one line saying when the cache was last checked and what came of it. It exists because a healthy check writes nothing (the file was already current), so the cache's own age proves nothing about whether anyone is still looking. Both files are generated and machine-local; put them in .gitignore:

dev/flowpad/tasks-cache.md
dev/flowpad/.tasks-cache-sync

B — the hosted connector

The channel that actually reads and writes the canvas, behind per-user auth. It runs the full toolset (retrieval, analysis, CRUD, templates, tasks) plus the same three local engine tools. It is served over Streamable HTTP by Flowpad's backend — its code is not in this repo, and it is never published to npm. Get its URL and sign in from Flowpad → Settings → Integrations.

Licence

This package is proprietary — see LICENSE. The published binary (dist/local.js) is a single esbuild bundle, so it also contains third-party open source components; each keeps its own licence, and all of them are reproduced in dist/THIRD-PARTY-NOTICES.txt inside the published package. That file is generated from the build's metafile (scripts/gen-third-party-notices.ts), so it lists exactly what the shipped bundle contains, and the build fails if a bundled component's licence text cannot be found.

Development

cd flowpad-mcp
yarn install
yarn dev        # the local stdio validator (src/local-index.ts)
yarn inspect    # open the MCP Inspector against it
yarn validate   # tsc + eslint + prettier + tool-parity + version-sync

• Entry: src/local-index.ts → createLocalServer (src/local-server.ts), which registers src/local-tools.ts. Published as the bundled bin dist/local.js (esbuild inlines flowpad-core, so the npx tool installs nothing).
• This repo hosts server A only. The hosted connector (B) lives in Flowpad's backend; nothing here may listen on a network port, and src/__tests__/local-only.contract.spec.ts fails the build if it does.
• The MCP tool surface is mirrored from the backend's tool catalog (src/generated/tool-catalog.json); scripts/check-tool-parity.ts asserts both the full (B) and local (A) surfaces against it.