Docs · MCP

Diagram from inside your AI agent

Flowgraf ships a Model Context Protocol server so any MCP client — Claude Code, Cursor, Windsurf, OpenCode — 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"]
    }
  }
}

OpenCode

Put this in the global config at ~/.config/opencode/opencode.json, or in opencode.json at the root of one project:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flowgraf": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "flowgraf-mcp"
      ],
      "enabled": true
    }
  }
}

Fully quit and restart OpenCode after saving the config. OpenCode reads project config from the current directory up to the nearest Git root when it starts.
Verify discovery with opencode mcp list. It should report flowgraf connected.
Start opencode in that project and paste the simple prompt below. Open the returned canvas link to verify the first call.

Current support boundary: Verified in OpenCode through the local stdio proxy. Direct remote Streamable HTTP configuration is not yet verified for Flowgraf in OpenCode; use the local config below. The proxy requires Node.js 18 or newer and downloads through npm on first start.

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. Simple web app
“Create an architecture diagram of a web app where users connect to a load balancer, which routes requests to two app servers backed by a Postgres database. Return the editable Flowgraf canvas link.”
2. RAG pipeline
“Create an architecture diagram of a RAG pipeline: a user query reaches an API, the API creates an embedding, searches a vector database, sends the retrieved context to an LLM, and returns the answer. Group ingestion separately with object storage, a document processor, and the same vector database. Return the editable Flowgraf canvas link.”
3. Edit an existing diagram
“Using the Flowgraf diagram from the previous response, insert a message queue between the API and the workers, preserve the existing components, and return 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.
OpenCode does not show Flowgraf as connected.: Run `opencode mcp list` from the same project. Confirm the config uses an array for `command`, then fully quit and restart OpenCode. Global config belongs at `~/.config/opencode/opencode.json`; project config belongs at the Git project root.
`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.