FlowZap

Welcome to FlowZap, the App to diagram with Speed, Clarity and Control.

FlowZap MCP Server Documentation

🤖 This documentation is optimized for LLM and AI Agent consumption

Version 1.3.6 | Last Updated: April 2026 | Stricter validation, ping-pong sequence enforcement, playground endpoint alignment

npm packageFlowZap Code SyntaxAgent APIOpenAPIPublic MCP Stats

Overview

The FlowZap MCP (Model Context Protocol) Server enables AI agents to create, validate, and share professional Workflow, Sequence and Architecture diagrams using FlowZap Code—a domain-specific language designed for machine-readable diagram generation.

Tip: Use it with the SKILL md file for optimal results!

What is FlowZap?

Purpose	Convert text-based code into visual workflow diagrams
Optimized For	AI-first generation, agentic workflows (n8n, Make.com, Zapier)
Unique Feature	Triple-view rendering - same code renders as workflow, sequence, AND architecture diagrams
Sharing	Instant shareable URLs without authentication

Security Guarantees

The FlowZap MCP Server implements enterprise-grade security measures to protect users:

Network Security

Protection	Implementation
SSRF Prevention	Only connects to flowzap.xyz and www.flowzap.xyz via HTTPS
URL Validation	All returned URLs are verified to originate from FlowZap domains
Request Timeout	30-second timeout prevents hanging connections

Input Validation

Limit	Value	Purpose
Max Code Length	50,000 characters	Prevents memory exhaustion
Max Input Length	100,000 characters	Protects against payload attacks
Null Byte Removal	Automatic	Prevents injection attacks
Control Character Sanitization	Automatic	Removes non-printable characters

Rate Limiting

Parameter	Value
Max Requests	30 per minute
Window Duration	60 seconds
Behavior	Returns retry-after time when exceeded

Data Privacy

• No Authentication Required - Public endpoints only
• No User Data Stored - Playground sessions are ephemeral (60-minute TTL, non-guessable cryptographic tokens)
• No Tracking - No cookies or persistent identifiers
• Logs to stderr only - Security events never exposed to MCP clients

Available Tools

1. flowzap_get_syntax

Purpose: Retrieve complete FlowZap Code syntax documentation.

When to Use: Before generating any FlowZap Code, call this tool to learn the correct syntax.

Input Schema:

{
  "type": "object",
  "properties": {}
}

Output: Complete syntax guide including global constraints, shape types, node syntax, edge syntax, loop syntax, and common mistakes to avoid.

2. flowzap_validate

Purpose: Validate FlowZap Code syntax before creating a diagram.

When to Use: Always validate code before calling flowzap_create_playground. This prevents errors and provides actionable feedback.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "FlowZap Code to validate"
    }
  },
  "required": ["code"]
}

Success Output:

✅ FlowZap Code is valid!

Stats:
- Lanes: 2
- Nodes: 5
- Edges: 4

Failure Output:

❌ Validation failed:
- Line 3: Unknown shape "oval". Valid shapes: circle, rectangle, diamond, taskbox
- Line 5: Edge missing handle syntax. Use: n1.handle(right) -> n2.handle(left)

3. flowzap_create_playground

Purpose: Create a shareable playground URL with the diagram.

When to Use: After validation passes, create a playground to give users an interactive diagram they can view and edit.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "FlowZap Code to load in the playground"
    },
    "view": {
      "type": "string",
      "enum": ["workflow", "sequence", "architecture"],
      "description": "Initial view mode. Default: workflow"
    }
  },
  "required": ["code"]
}

Output:

✅ Playground created!

🔗 **View your diagram:** https://flowzap.xyz/playground/abc123?view=architecture

The diagram is ready to view and edit. Share this link with anyone!

View Modes:

View	Best For
workflow	Step-by-step process flows (default)
sequence	Message exchanges between participants
architecture	System-level overview showing lanes as systems

Important Notes:

• Automatically validates code before creating playground
• Returns validation errors if code is invalid
• Playground URLs expire after 60 minutes
• No authentication required to view
• Use view="architecture" for system-level overview of multi-lane diagrams

Validation Rules Reference

The validator performs comprehensive validation checks across multiple categories. Understanding these helps generate valid code on the first attempt.

Error Codes (Block Diagram Creation)

Code	Description	Fix
CONTAINS_EMOJI	Emoji characters detected	Use UTF-8 plain text only
NESTED_LANE	Lane defined inside another lane	Flatten lane structure
UNMATCHED_BRACE	Closing } without opening {	Check brace balance
UNCLOSED_BRACE	Missing closing }	Add closing brace
DUPLICATE_NODE_ID	Same node ID used twice	Use unique IDs: n1, n2, n3...
INVALID_SHAPE	Unknown shape type	Use: circle, rectangle, diamond, taskbox
MISSING_LABEL	Node without label (except taskbox)	Add label:"Text"
NODE_OUTSIDE_LANE	Node defined outside any lane	Move inside a lane block
MISSING_HANDLES	Edge without handle syntax	Use n1.handle(right) -> n2.handle(left)
INVALID_EDGE_SYNTAX	Malformed edge definition	Check arrow syntax ->
INVALID_DIRECTION	Unknown handle direction	Use: left, right, top, bottom
EDGE_OUTSIDE_LANE	Edge defined outside any lane	Move inside a lane block
UNDEFINED_LANE_REF	Cross-lane ref to non-existent lane	Check lane name spelling
INVALID_LOOP_SYNTAX	Malformed loop definition	Use loop [condition] n1 n2
LOOP_OUTSIDE_LANE	Loop defined outside any lane	Move inside a lane block
MISPLACED_COMMENT	Comment in wrong location	Put the only allowed comment on the same line as the lane opening brace
COMMENT_OUTSIDE_LANE	Comment outside any lane	Remove it or move the display label onto the lane opening line
UNDEFINED_NODE	Edge references undefined node	Define node before referencing
NON_SEQUENTIAL_NUMBERING	Node numbering does not start at n1 or has a gap	Use n1, n2, n3... sequentially across the whole diagram
WRONG_LABEL_SYNTAX	Node label uses = instead of :	Use label:"Text" for node attributes
WRONG_EDGE_LABEL_SYNTAX	Edge label uses : instead of =	Use [label="Text"] for edge labels
ORPHAN_NODE	Node is not connected to any edge	Connect it as a source or target edge, or remove it
MISSING_RETURN_EDGE	Cross-lane request has no corresponding return edge	Add a response edge from the target lane back to the source lane
MULTIPLE_OUTBOUND_REQUESTS	A lane sends another cross-lane request before the prior one is answered	Use a strict request → response → next request rhythm
CHRONOLOGICAL_PAIRING_VIOLATION	A different cross-lane request appears before the previous return edge	Reorder edges to match the true request/response timeline
EMPTY_DIAGRAM	No nodes defined	Add at least one node
WRONG_DSL_FORMAT	Mermaid/PlantUML detected	Use FlowZap syntax only

Warning Codes (Best Practice Violations)

Code	Description	Recommendation
NON_PRINTABLE_CHARS	Control characters detected	Use plain text only
DUPLICATE_LANE	Same lane defined twice	Merge into single block
MISSING_LANE_LABEL	Lane without # Display Name	Add display label
NON_STANDARD_NODE_ID	ID not in n1, n2, n3 format	Use standard numbering
TASKBOX_MISSING_PROPS	Taskbox without owner/description	Add required properties
LOOP_TOO_FEW_NODES	Loop with only 1 node	Include at least 2 nodes
UNKNOWN_ATTRIBUTE	Non-standard attribute used	Use: label, owner, description, system
LABEL_TOO_LONG	Label exceeds 50 characters	Keep labels concise

FlowZap Code Syntax Quick Reference

Global Constraints

✓ UTF-8 plain text only (no emojis)
✓ Node IDs: n1, n2, n3... (globally unique, sequential, no gaps)
✓ Shapes: circle, rectangle, diamond, taskbox
✓ Attributes: label, owner, description, system
✓ Comments: Only "# Display Label" on the same line as the lane opening brace
✓ Sequence view: alternate cross-lane request and response edges in real chronological order
✗ No Mermaid, PlantUML, or other DSL syntax

Basic Structure

laneName { # Lane Display Name
  n1: circle label:"Start"
  n2: rectangle label:"Process"
  n1.handle(right) -> n2.handle(left)
}

Shape Types

Shape	Purpose	Example
circle	Start/End events	n1: circle label:"Start"
rectangle	Tasks/Activities	n2: rectangle label:"Process Order"
diamond	Decision gateways	n3: diamond label:"Valid?"
taskbox	Assigned tasks	n4: taskbox owner:"Alice" description:"Deploy"

Edge Syntax

# Basic edge
n1.handle(right) -> n2.handle(left)

# Edge with label
n2.handle(bottom) -> n3.handle(top) [label="Yes"]

# Cross-lane edge (prefix with lane name)
n3.handle(right) -> fulfillment.n4.handle(left) [label="Send"]

Handle Directions

Direction	Position
left	Left side of node
right	Right side of node
top	Top of node
bottom	Bottom of node

Loop Syntax

loop [retry up to 3 times] n1 n2 n3

• Must be inside a lane block
• Cannot be nested
• Should reference at least 2 nodes

Complete Example

sales { # Sales Team
  n1: circle label:"Order Received"
  n2: rectangle label:"Validate Order"
  n5: rectangle label:"Receive decision"
  n1.handle(right) -> n2.handle(left)
  n2.handle(bottom) -> fulfillment.n3.handle(top) [label="Submit"]
}

fulfillment { # Fulfillment
  n3: rectangle label:"Review Order"
  n4: rectangle label:"Return decision"
  n3.handle(right) -> n4.handle(left)
  n4.handle(top) -> sales.n5.handle(bottom) [label="Approved"]
}

Recommended Workflow for AI Agents

1. Step 1: Learn Syntax
   {"name": "flowzap_get_syntax", "arguments": {}}}
2. Step 2: Generate Code
   Based on user request, generate FlowZap Code following the syntax rules.
3. Step 3: Validate
   {"name": "flowzap_validate", "arguments": {"code": "..."}}
4. Step 4: Fix Errors (if any)
   Parse error messages and correct the code.
5. Step 5: Create Playground
   {"name": "flowzap_create_playground", "arguments": {"code": "..."}}
6. Step 6: Present to User
   Share the playground URL with the user.

Common Mistakes to Avoid

Mistake	Incorrect	Correct
Lane comment on separate line	laneName { # Label	laneName { # Label
Abbreviated shapes	n1: rect	n1: rectangle
Missing handles	n1 -> n2	n1.handle(right) -> n2.handle(left)
Wrong node attribute syntax	label="Text"	label:"Text"
Wrong edge label syntax	[label:"Text"]	[label="Text"]
Emojis in labels	label:"Start 🚀"	label:"Start"
Unknown attributes	priority:"high"	(remove - not supported)
Non-sequential IDs	n1, n3, n5	n1, n2, n3
Undefined lane refs	undefined.n5	Use actual lane name
Second request before response	A -> B, then A -> C, then B -> A	A -> B, then B -> A, then next request

API Endpoints (Direct Access)

For agents that prefer direct HTTP calls instead of MCP:

POST /api/validate

URL: https://flowzap.xyz/api/validate

Rate Limit: 30 requests/minute per IP

Request:

{
  "code": "process { # P n1: circle label:\"Start\" }"
}

Response:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "stats": {
    "lanes": 1,
    "nodes": 1,
    "edges": 0,
    "loops": 0
  }
}

POST /api/playground/create

URL: https://flowzap.xyz/api/playground/create

Rate Limit: 5 requests/minute, 50/day per IP

Request:

Response:

{
  "url": "https://flowzap.xyz/playground?session=abc123"
}

Installation

The FlowZap MCP Server works with any tool that supports the Model Context Protocol (MCP). Here is the complete list of compatible tools:

All Compatible Coding Tools

Tool	How to Configure
Claude Desktop	Add to claude_desktop_config.json:macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json
Claude Code	Run: claude mcp add --transport stdio flowzap -- npx [email protected] add to .mcp.json in your project root.
Cursor	Open Settings → Features → MCP Servers → Add Server. Use the same JSON config.
Windsurf IDE	Add to ~/.codeium/windsurf/mcp_config.json
OpenAI Codex	Add to ~/.codex/config.toml:[mcp_servers.flowzap]command = "npx"args = ["[email protected]"]Or run: codex mcp add flowzap -- npx [email protected]
Warp Terminal	Settings → MCP Servers → Click "+ Add" → Paste the JSON config.
Zed Editor	Add to settings.json:{"context_servers": {"flowzap": {"command": "npx", "args": ["[email protected]"]}}}
Cline (VS Code)	Open Cline sidebar → MCP Servers icon → Edit cline_mcp_settings.json
Roo Code (VS Code)	Add to .roo/mcp.json in project or global settings.
Continue.dev	Create .continue/mcpServers/flowzap.yaml with:name: FlowZapmcpServers: - name: flowzap command: npx args: ["[email protected]"]
Sourcegraph Cody	Add to VS Code settings.json via openctx.providers configuration.

Windows Users: If tools don't appear, use the absolute path: "command": "C:\\Program Files\\nodejs\\npx.cmd". Find your npx path with: where.exe npx

JSON Configuration

All tools use the same JSON configuration format:

{
  "mcpServers": {
    "flowzap": {
      "command": "npx",
      "args": ["[email protected]"]
    }
  }
}

Support & Resources

• • Syntax Documentation: https://flowzap.xyz/flowzap-code
• • Interactive Playground: https://flowzap.xyz/playground
• • Template Library: https://flowzap.xyz/templates
• • Public MCP Usage Stats: https://flowzap.xyz/.well-known/flowzap-stats.json
• • npm Package: https://www.npmjs.com/package/flowzap-mcp
• • GitHub Repository: https://github.com/flowzap-xyz/flowzap-mcp
• • Official MCP Registry: https://registry.modelcontextprotocol.io/?q=flowzap
• • Smithery Server: https://smithery.ai/server/@flowzap/flowzap
• • Smithery Skill: https://smithery.ai/skills/Flowzap/diagram-skill
• • PulseMCP: https://www.pulsemcp.com/servers/flowzap
• • Glama: https://glama.ai/mcp/servers/flowzap-xyz/flowzap-mcp
• • MCPServers.org: https://mcpservers.org/servers/flowzap-xyz-docs-mcp
• • AIBase: https://mcp.aibase.com/server/1639702939289526535
• • Agent Skill (skills.sh): https://skills.sh/flowzap-xyz/flowzap-mcp/flowzap-diagrams
• • Skill Source: https://github.com/flowzap-xyz/flowzap-mcp/tree/main/skills/flowzap-diagrams
• • Hugging Face Dataset: https://huggingface.co/datasets/Jules-OC/flowzap-sequence-workflows/tree/main

Install as Agent Skill (40+ agents)

npx skills add flowzap-xyz/flowzap-mcp

Compatible with: Claude Code, Cursor, Windsurf, Codex, Gemini CLI, GitHub Copilot, Cline, Roo Code, Augment, OpenCode, and more.

Version History

Version	Date	Changes
1.3.6	Apr 2026	Stricter validation (numbering gaps, ping-pong sequence enforcement, same-line lane labels), playground endpoint alignment, updated docs
1.3.5	Feb 2026	Security fixes: MCP SDK ReDoS, hono JWT/XSS, ajv ReDoS, qs DoS vulnerabilities
1.3.3	Feb 2026	All 7 tools wired, Architecture view mode
1.3.0	Feb 2026	Added Architecture view mode, triple-view rendering
1.2.0	Jan 2026	Added new validation rules, comprehensive test coverage
1.1.0	Dec 2025	Security hardening, rate limiting
1.0.0	Nov 2025	Initial release

This documentation is optimized for LLM consumption. For human-readable guides, visit flowzap.xyz/flowzap-code