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?

Security Guarantees

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

Network Security

Input Validation

Rate Limiting

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

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

2. flowzap_validate

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

✅ FlowZap Code is valid!

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

❌ 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

{
  "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"]
}

✅ 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!

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)

Warning Codes (Best Practice Violations)

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

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

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

Common Mistakes to Avoid

API Endpoints (Direct Access)

For agents that prefer direct HTTP calls instead of MCP:

POST /api/validate

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

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

POST /api/playground/create

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

{
  "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

JSON Configuration

All tools use the same JSON configuration format:

{
  "mcpServers": {
    "flowzap": {
      "command": "npx",
      "args": ["flowzap-mcp@1.3.6"]
    }
  }
}

Support & Resources

npx skills add flowzap-xyz/flowzap-mcp

Version History