Docs · MCP

Diagram from inside your AI agent

Flowgraf ships a Model Context Protocol server so any MCP client — Claude Code, Cursor, Windsurf — can create and edit real architecture diagrams. Your agent authors the graph; Flowgraf validates it, lays it out, renders it, and hands back a link to a live canvas. There’s no API key and no LLM cost to you — the calling agent does the thinking.

The three tools

Tool	What it does
create_diagram	Turn a graph (nodes + edges + groups) into a diagram → returns an SVG, a Mermaid string, and a `/d/<id>` canvas link.
edit_diagram	Apply operations to an existing diagram (e.g. insert a cache between two nodes) — it re-wires and re-lays-out automatically.
get_diagram	Fetch a diagram’s current graph + version.

Claude Code

Recommended — the hosted remote endpoint (no local process to run):

terminal

$ claude mcp add --transport http flowgraf https://flowgraf.in/api/mcp

Or run it through the stdio proxy on npm:

terminal

$ claude mcp add flowgraf -- npx -y flowgraf-mcp

Then ask your agent for a diagram (see the example prompts). Restart Claude Code if the tools don’t appear immediately.

Cursor & Windsurf

Add the stdio proxy to your MCP config — ~/.cursor/mcp.json (Cursor) or your Windsurf MCP settings:

mcp.json

{
  "mcpServers": {
    "flowgraf": {
      "command": "npx",
      "args": ["-y", "flowgraf-mcp"]
    }
  }
}

Any other MCP client

The proxy speaks MCP over stdio and forwards to the hosted API. Point any stdio client at:

terminal

$ npx -y flowgraf-mcp

By default it targets the hosted endpoint. Override it (e.g. self-hosting or local dev) with an environment variable:

Variable	Meaning
FLOWGRAF_MCP_URL	Full endpoint URL, e.g. `http://localhost:3000/api/mcp`
FLOWGRAF_MCP_BASE_URL	Base URL; `/api/mcp` is appended.

The remote endpoint is https://flowgraf.in/api/mcp (Streamable HTTP).

Example agent prompts

Once the server is added, just ask in natural language:

1“Create an architecture diagram of a 3-tier web app on AWS: a user hits a load balancer in a VPC, which fans out to two app servers backed by a Redis cache and an RDS Postgres database.”
2“Diagram a RAG pipeline: a user query goes to an app server, which embeds it, searches a vector database, and calls an LLM with the retrieved context. Give me the link.”
3“On that diagram, insert a message queue between the API and the workers, then send me the updated canvas link.”

Each returns a rendered diagram plus a /d/<id> link. Open it to keep editing on the canvas — by hand, or by chatting.

Troubleshooting

The tools don’t show up in my client.: Fully restart the client after adding the server — most MCP clients only read their server list on startup. In Claude Code, `claude mcp list` should show `flowgraf` as connected.
`npx flowgraf-mcp` says command/package not found.: Ensure Node.js 18+ is installed (`node -v`). The `-y` flag lets npx install the package on first run without a prompt.
Connection refused / the tools error out.: Check you can reach the endpoint: `curl -i https://flowgraf.in/api/mcp` should not connection-refuse. If you set FLOWGRAF_MCP_URL for local dev, make sure your dev server is running.
Do I need an API key?: No. The MCP path has no API key and no LLM cost — your agent authors the diagram operations and Flowgraf validates, lays out, and renders them. Diagrams created via MCP are anonymous; open the returned link and sign in to save one to your account.
My agent tried to set x/y coordinates and it was rejected.: That’s by design — no model ever places a box. Author only semantics (nodes, groups, edges); the layout engine computes all geometry.

Prefer the browser? Open a blank canvas and just describe what you’re building.