Overview

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

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 (15-minute TTL)
• 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" after lane opening brace
✗ 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"
  n3: diamond label:"Valid?"
  n1.handle(right) -> n2.handle(left)
  n2.handle(right) -> n3.handle(left)
  n3.handle(right) -> fulfillment.n4.handle(left) [label="Yes"]
  n3.handle(bottom) -> n6.handle(top) [label="No"]
  n6: rectangle label:"Reject Order"
}

fulfillment {
  # Fulfillment
  n4: rectangle label:"Process Order"
  n5: circle label:"Complete"
  n4.handle(right) -> n5.handle(left)
}

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": ["-y", "flowzap-mcp"]
    }
  }
}

Support & Resources

Version History