The flowss MCP server

flowss runs a Model Context Protocol (MCP) server, so AI assistants and agents outside flowss (Claude Code, Claude Desktop, Cursor, VS Code, or software you write yourself) can use flowss as a tool: look up engines and templates, check whether a diagram parses and renders, critique it, convert it between notations, generate a new diagram from a sentence, render it to SVG or PNG, diff two versions, and run the Science studio's checkers. This page explains what the server offers, how to connect a client step by step, every tool with its arguments and results, what is free and what is metered, the limits, and every error you can meet. It is a developer page, so it shows HTTP requests, headers and JSON. For the rest of the API, see The REST API and Embedding and the render API.

At a glance

What you can do with it

A useful pattern for an agent: generate or edit a diagram, call verify_diagram to make sure it parses and draws, then critique_diagram to improve it, then render_diagram for the image.

Before you start

• For the free tools: nothing. You can connect without an account.
• For the keyed tools: a flowss account and an API key. API keys can be created on any plan.
• For the AI tools (generate_diagram, and AI conversion or AI detection): hosted AI points, which come with Plus (200 a month), Ultra and Enterprise (600 a month), or points you bought earlier. Over MCP, AI always runs on hosted points: your own AI provider key, whether kept in your browser or saved to your account, is not used for MCP calls. On Free and Starter without bought points, generate_diagram returns the same "no points" message the app shows, while detect_engine and convert_engine fall back to their free answers where they have one (see each tool below). See AI points and limits.

Step 1: Create a flowss API key

1. Sign in and open your account page.
2. Find the API keys panel ("For the headless /api/render endpoint (which needs a key or a signed-in session), the /api/v1 endpoints and the MCP server — wire diagrams into CI, docs builds, or back-end pipelines. Cleartext is shown ONCE on creation.").
3. Type a name in Key name (e.g. CI pipeline), for example "Claude Desktop", and click Create key. A blank name becomes "Untitled".
4. The panel shows New key — copy now, won't show again with the key, which starts with glyp_. Click Copy and store the key somewhere safe, such as a password manager. Then click Dismiss.
5. The key now appears in the list with its name, its first characters (glyp_xxxxx…), "never used" or the date it was last used, and the date it was created. (Until you create one, the list reads "No API keys yet.")

flowss stores only a fingerprint of the key, never the key itself, so a lost key cannot be shown again: revoke it and create a new one. Revoke asks "Revoke this key? Existing integrations using it will stop working immediately." and takes effect at once.

Tip: Create one key per client or machine. Each key appears separately in the list with its own "last used" date, so you can revoke one without breaking the others. All of an account's keys share the same daily allowances.

Step 2: Check the server answers

Discovery needs no key:

curl https://www.flowss.ai/api/mcp

It returns the server name and version, the protocol version, the endpoint, a line about authentication, the methods and the tool definitions.

The JSON-RPC handshake:

curl -X POST https://www.flowss.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "glyph", "version": "1.0.0" }
  }
}

Your key, on a keyed tool:

curl -X POST https://www.flowss.ai/api/mcp \
  -H 'Authorization: Bearer glyp_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "generate_diagram",
      "arguments": { "prompt": "three-tier web app with a cache and a Postgres DB" }
    }
  }'

If that returns a diagram, your key works and your account has points. The server also accepts the key without the Bearer prefix.

Step 3: Connect your client

Point your client at https://www.flowss.ai/api/mcp using its HTTP transport (some clients call it "Streamable HTTP"), and add the Authorization header with your key. The client then discovers the tools by itself through tools/list. Leave the header out to use only the free tools.

Things to know about this server when you configure a client:

• It authenticates with the Authorization header only. It has no OAuth sign-in flow, so a client that can only add remote servers through an OAuth sign-in needs a bridge (see Claude Desktop below).
• It answers every POST with a single JSON response. It does not stream events to the client, and a GET returns the JSON description above rather than an event stream.
• It always answers initialize with protocol version 2024-11-05, whatever version your client proposes, and it does not issue session ids.

The examples below were written for each client's current configuration format. Client formats change; if a field is not recognised, check your client's own MCP documentation and keep the same URL and header.

Claude Code

claude mcp add --transport http flowss https://www.flowss.ai/api/mcp \
  --header "Authorization: Bearer glyp_YOUR_KEY"

Then ask, for example, "Use flowss to draw our login flow as a sequence diagram and verify it."

Cursor

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "flowss": {
      "url": "https://www.flowss.ai/api/mcp",
      "headers": { "Authorization": "Bearer glyp_YOUR_KEY" }
    }
  }
}

VS Code

Add the server to .vscode/mcp.json in your workspace:

{
  "servers": {
    "flowss": {
      "type": "http",
      "url": "https://www.flowss.ai/api/mcp",
      "headers": { "Authorization": "Bearer glyp_YOUR_KEY" }
    }
  }
}

Claude Desktop

If your version of Claude Desktop cannot add a remote server with a custom Authorization header, connect through a local bridge instead. The community mcp-remote package (not made by flowss) runs with Node.js and forwards a header; add this to Claude Desktop's configuration file (claude_desktop_config.json) and restart Claude Desktop:

{
  "mcpServers": {
    "flowss": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.flowss.ai/api/mcp",
        "--header",
        "Authorization:${FLOWSS_AUTH}"
      ],
      "env": { "FLOWSS_AUTH": "Bearer glyp_YOUR_KEY" }
    }
  }
}

Putting the key in env keeps the space in "Bearer glyp_…" out of the command line, which some systems split on.

Your own code

Any HTTP client can speak to the server directly: send JSON-RPC 2.0 messages by POST with Content-Type: application/json. A typical session is initialize, then tools/list, then any number of tools/call. There is no session to keep: each request stands alone.

import requests

URL = "https://www.flowss.ai/api/mcp"
HEADERS = {"Authorization": "Bearer glyp_YOUR_KEY"}

def call(tool, arguments, id=1):
    body = {"jsonrpc": "2.0", "id": id, "method": "tools/call",
            "params": {"name": tool, "arguments": arguments}}
    r = requests.post(URL, json=body, headers=HEADERS, timeout=70)
    return r.json()

print(call("verify_diagram", {"engine": "mermaid", "code": "graph LR\n  A --> B"}))

Step 4: Try it

Ask your assistant something that needs flowss, for example:

• "List the flowss engines that can draw entity-relationship diagrams."
• "Generate a Mermaid sequence diagram of a password reset, then verify it with flowss."
• "Critique this D2 diagram and apply the top three suggestions."
• "Convert this Graphviz graph to D2."
• "Render this diagram as a dark PNG 1,600 pixels wide."

Your assistant shows each tool call it makes. Generated diagrams come back with an embed_url you can open in a browser to see the figure.

The tools

list_engines

No arguments. Returns { "count": N, "engines": [{ "id", "name", "language", "description" }] } for every engine flowss supports. Use it before generating or converting, to pick an engine id. The engines themselves are documented at /docs/engines.

search_templates

Returns { "count", "templates": [{ "id", "title", "engine", "description" }] }. With no arguments it returns the first 20 templates. See The template gallery.

detect_engine

The built-in matcher runs first, with no key. When it is confident, the answer is { "engine", "confidence": "high" or "medium", "source": "heuristic" }. When it is not:

• Without a key, you get its best guess marked as such: { "engine", "confidence": "low", "source": "heuristic" } (mermaid when it has no guess at all).
• With a key, the AI classifies the snippet and returns "source": "ai", for 1 point once the AI has answered. If your account has no points, you get the low-confidence guess instead of an error.

convert_engine

How it converts:

The built-in converters cover a Mermaid flowchart to D2 or PlantUML, D2 to Mermaid, Graphviz to D2, DBML to Mermaid (ER) or ERD, Markmap to a Weave mind map (lucidflow), and a Weave board to Mermaid, Graphviz, D2 or PlantUML. Without a key, a pair that needs AI returns the key-required message (or the lossy result, when there is one). With a key, the call goes on to the conversion service, which first tries one more free step: when you passed sourceEngine and asked for targetEngine: "lucidflow", it lays a graph-like source onto a Weave canvas structurally, with no AI and no point. With a key but no points, the lossy result is returned when there is one; otherwise the points message.

verify_diagram

A mechanical check with no AI: does the source parse in its own notation, is it complete, do references resolve, does the engine's own checker accept it, and does it actually draw. Returns { "ok", "summary", "defects": [...] }, where a blocking defect fails the diagram and an advisory one is a note. It runs the same checks as the Studio's status bar.

critique_diagram

The whole deterministic read, with no AI. Returns:

• readiness: the level the diagram earns (empty, draft, sound, reviewed, publishable), with a label, a score, the reason and what blocks the next level;
• verification: as verify_diagram;
• critique: an overall score, a band, a summary, and seven dimensions (fidelity, completeness, structure, legibility, rigour, accessibility, portability), each with its findings and the concrete edit that would improve it, plus suggested moves. A dimension that cannot be judged is reported as unassessed, never as a pass;
• findings: the readiness findings.

generate_diagram

Generates a complete diagram with hosted AI and returns:

{
  "engine": "d2",
  "title": "Food delivery — containers",
  "code": "…the diagram source…",
  "embed_url": "https://www.flowss.ai/embed?engine=d2&code=…&theme=dark",
  "links": {
    "embed": "https://www.flowss.ai/embed?engine=d2&code=…&theme=dark",
    "render": "https://www.flowss.ai/api/render"
  }
}

It costs 1 point, charged once the AI has answered, even if the answer then cannot be used ("The model returned malformed output."). It also counts toward your account's daily generation allowance: 60 a day on Free and Starter, 200 on Plus, 400 on Ultra and 500 on Enterprise. That allowance is counted before points are checked, so a call refused for lack of points still uses one. A generation may take up to 30 seconds. If the model names an engine flowss does not know, the result falls back to the engine you asked for, or to mermaid; a missing title becomes "Diagram".

render_diagram

Returns the SVG as text, or the PNG as an image content block. GET https://www.flowss.ai/api/render lists which engines can be rendered and why the others cannot. A PNG that would exceed the render service's megapixel limit at the requested width is drawn narrower, or refused when even that is too large; ask for svg instead, which has no pixel limit. Source over 100 KB is refused ("Source is too large (>100 KB)…"). Rendering counts toward your account's daily render allowance of 60, shared with diff_diagrams, check_science and the REST render API. See Embedding and the render API.

diff_diagrams

Returns { "engine", "structured", "parseable_engine", "changed", "textChanged", "summary", "diff" }. For Mermaid (flowcharts), D2, Graphviz, DBML, Structurizr, SQL, ERD and OpenAPI the diff is structural when the source parses (added, removed and renamed nodes and edges; for SQL and DBML schemas, columns added, removed or retyped); otherwise structured is false and changed reflects a whitespace-insensitive text comparison. The summary is one line, such as "Added 1 edge (b→c).", "The source changed." or "No change." Each source may be up to 256 KB ("Source too large (>256 KB).").

check_science

Runs the Science studio's deterministic checkers and model analysers. The checker operations include verify (a whole figure's claims, or a list of labels), balance, redox, oxidation-states, molar-mass, convert (units), dimension, check-equation, quantity, compare, constant, identifier, notation, pathway, figure-standards, palette, alt-text, accessibility, taxonomy, critique-design, randomise, factorial, replication, spectrum, beer-lambert, nmr-frequency, reporting-guideline, risk-of-bias and hazards. The model operations compute a Science figure's models: model, simulate, steady-state, r0, fit, sensitivity, montecarlo (a seed is required, at most 500 draws), graph, describe, regress, pi-groups, ledger-check and quantities. Every number a model operation computes comes back with a provenance entry naming its method and version. An unknown op is refused with the list of valid ones; GET https://www.flowss.ai/api/v1/science documents each operation's fields. See Science and The REST API.

Methods and messages

• notifications/initialized (and any unknown method sent without an id) is a notification and gets no reply; sent on its own, it is answered with HTTP 202 and no body.
• A message without "jsonrpc": "2.0" or a method is answered with the error "Invalid Request".
• A batch is a JSON array of up to 20 messages. They run one at a time, in order, and the response is an array of the results.
• A batch stops starting new tool calls about 25 seconds in, so that the slowest call it started can still finish within the request's 60-second limit. Each call it did not start is answered with "Deadline exceeded: this batch ran out of time before this call could start, so it was not run and nothing was charged. Send it again in a smaller batch." The finished results are returned as normal.
• A request body may be up to about 4 MB.

Tool results

A successful call returns an MCP content array: a text block holding JSON (pretty-printed), the SVG text for render_diagram in SVG, or an image block (data in base64, mimeType: "image/png") for a PNG. A tool that fails returns a normal result with isError: true and a text block saying why, so your assistant can read it and react. JSON-RPC errors are used for problems with the request itself (invalid JSON, an unknown method or tool, an oversized batch) and for the daily limits.

Limits and metering

All daily limits reset at midnight UTC. A keyed call to an AI tool is counted once, by the AI feature it reaches, never twice. Hosted AI over MCP also falls under flowss's daily safety limits on hosted AI (see AI points and limits).

Security

• Your key travels only in the header of your requests to flowss. flowss uses it to identify your account and charge your points; it is never sent to an AI provider.
• A key that does not verify is treated as no key. A mistyped or revoked key is not passed on to anything: the request is handled as keyless, the free tools still answer, and the keyed tools reply with the key-required message.
• Revoking a key takes effect immediately for every client using it.
• Treat the key like a password. Anyone holding it can spend your account's points and daily allowances. Prefer an environment variable or your client's secret storage to pasting it into shared files, and do not commit configuration files that contain it.
• The server holds no session state. Each request stands alone, so there is nothing to sign out of; to cut a client off, revoke its key.

Tips

• Give your assistant the order "generate, then verify, then critique": verify_diagram and critique_diagram are free, and catch most problems before you render or publish.
• Pass sourceEngine to convert_engine whenever you know it. Without it the built-in converters cannot be used, and every conversion needs AI.
• Pass the original request to critique_diagram as request to get the fidelity score.
• Ask for SVG unless you need a PNG: SVG stays sharp at any size and has no pixel limit.
• Keep batches small when they include generate_diagram, which can take up to 30 seconds per call.
• Use one API key per client so you can see each one's "last used" date and revoke one alone.
• Watch your points in your account menu or on your account page; every MCP generation appears in Points history as a Hosted AI call.

Limits and known constraints

• Over MCP, AI tools always use hosted AI points. Your own AI provider key is not used, so on Free and Starter the AI tools work only with points bought earlier on a plan with an allowance.
• Authentication is by API key header only; there is no OAuth sign-in.
• The server does not stream: every request gets one JSON response, and there are no server-initiated notifications.
• The server offers tools only. It has no MCP resources or prompts.
• render_diagram draws only the engines flowss can render on its servers; GET /api/render lists them.
• generate_diagram charges its point once the AI has answered, even if the answer is malformed.
• The free tools are capped at 200 calls a day per account with a key, and 200 requests a day per network address without one. Several people behind one office or campus address share the keyless allowance.
• The server's handle is glyph; some clients show that name next to its tools.

Troubleshooting

Related pages

• The REST API
• Embedding and the render API
• Integrations and extensions
• AI points and limits
• AI in flowss
• Bring your own AI key
• Account settings and your data
• Choosing an engine