# FlowZap MCP Server - Complete Documentation for AI Agents

**Version:** 1.4.3  
**Last Updated:** May 2026  
**Target Audience:** LLMs, AI Agents, and Agentic Systems  
**Official Documentation:** https://flowzap.xyz/flowzap-code

---

## 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?

FlowZap is a diagramming platform that converts text-based code into visual workflow diagrams. Unlike Mermaid or PlantUML, FlowZap Code is specifically designed for:

- **AI-first generation** - Optimized syntax for LLM output
- **Agentic workflows** - Built for automation pipelines (n8n, Make.com, Zapier)
- **Triple-view rendering** - Same code renders as workflow, sequence, AND architecture diagrams
- **Instant sharing** - Generate 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 (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`

**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:**
```json
{
  "type": "object",
  "properties": {}
}
```

**Output:** Complete syntax guide including:
- Global constraints
- Shape types (circle, rectangle, diamond, taskbox)
- Node syntax with examples
- Edge syntax with handle directions
- Loop syntax
- Common mistakes to avoid

**Example Call:**
```json
{
  "name": "flowzap_get_syntax",
  "arguments": {}
}
```

---

### 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.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "FlowZap Code to validate"
    }
  },
  "required": ["code"]
}
```

**Output Structure:**
```
✅ FlowZap Code is valid!

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

Or on failure:
```
❌ 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)
```

**Example Call:**
```json
{
  "name": "flowzap_validate",
  "arguments": {
    "code": "process {\n  # Process\n  n1: circle label:\"Start\"\n  n2: rectangle label:\"End\"\n  n1.handle(right) -> n2.handle(left)\n}"
  }
}
```

---

### 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.

**Input Schema:**
```json
{
  "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 for the diagram. Default: workflow"
    }
  },
  "required": ["code"]
}
```

**Output:**
```
✅ Playground created!

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

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

**Important Notes:**
- Automatically validates code before creating playground
- Returns validation errors if code is invalid
- Playground URLs expire after 15 minutes of inactivity
- No authentication required to view
- Use `view="architecture"` for system-level overview of multi-lane diagrams

**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 |

**Example Call:**
```json
{
  "name": "flowzap_create_playground",
  "arguments": {
    "code": "sales {\n  # Sales Team\n  n1: circle label:\"Order Received\"\n  n2: rectangle label:\"Process Order\"\n  n1.handle(right) -> n2.handle(left)\n}",
    "view": "architecture"
  }
}
```

---

### 4. `flowzap_export_graph`

**Purpose:** Export FlowZap Code as a structured JSON graph (lanes, nodes, edges) for AI reasoning and programmatic analysis.

**When to Use:** When you need to analyze diagram structure programmatically or inspect relationships.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "code": { "type": "string", "description": "FlowZap Code to parse" }
  },
  "required": ["code"]
}
```

**Output:** JSON with `lanes`, `nodes`, and `edges` arrays.

---

### 5. `flowzap_artifact_to_diagram`

**Purpose:** Parse HTTP logs, OpenAPI specs, or code snippets into FlowZap Code diagrams.

**When to Use:** When converting raw technical artifacts into visual workflows.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "artifactType": { "type": "string", "enum": ["http_logs", "openapi", "code"] },
    "content": { "type": "string", "description": "Raw artifact content" },
    "view": { "type": "string", "enum": ["workflow", "sequence", "architecture"] }
  },
  "required": ["artifactType", "content"]
}
```

**Output:** FlowZap Code and playground URL.

---

### 6. `flowzap_diff`

**Purpose:** Compare two versions of FlowZap Code and get a structured diff showing what changed (nodes/edges added, removed, updated).

**When to Use:** When explaining changes between diagram versions to users.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "oldCode": { "type": "string" },
    "newCode": { "type": "string" }
  },
  "required": ["oldCode", "newCode"]
}
```

**Output:** Structured diff with added, removed, and updated elements.

---

### 7. `flowzap_apply_change`

**Purpose:** Apply structured patch operations (insert/remove/update nodes or edges) to FlowZap Code. Safer than regenerating entire diagrams — preserves existing structure.

**When to Use:** When making incremental changes to existing diagrams.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "code": { "type": "string" },
    "operations": { "type": "array", "description": "Array of patch operations (insertNode, removeNode, updateNode, insertEdge, removeEdge)" }
  },
  "required": ["code", "operations"]
}
```

**Output:** Updated FlowZap Code and playground URL.

---

### 8. `flowzap_compliance_check`

**Purpose:** Run automated SOC2, GDPR, and PIPL compliance analysis on a FlowZap Code data-flow diagram. Returns a Markdown audit report with risks, recommendations, and a link to the manual checker.

**When to Use:** When the user asks for a privacy, security, or regulatory review of a data-flow diagram. Backed by Deepseek LLM.

**Input Schema:**
```json
{
  "type": "object",
  "properties": {
    "code": { "type": "string", "maxLength": 50000 },
    "lng": { "type": "string", "enum": ["en", "fr", "zh"], "default": "en" }
  },
  "required": ["code"]
}
```

**Output:** Markdown audit report covering SOC2 CC-series controls, GDPR articles, and PIPL chapters with risks, recommendations, and a shareable ephemeral result URL (60-minute TTL).

**Rate Limits (strict, Deepseek LLM cost protection):**
- **3 successful calls per day** per IP or per mcpIdentity
- **1 call per hour** burst limit per IP
- **Global 5-minute circuit breaker** on repeated upstream failures
- Only successful calls count toward the daily quota

---

## Public API Endpoints

These endpoints are available for external integrations (no authentication required):

| Endpoint | Method | Rate Limit | Description |
|----------|--------|------------|-------------|
| `/api/validate` | POST | 30/min | Validate FlowZap Code syntax |
| `/api/playground/create` | POST | 5/min, 50/day | Create ephemeral playground URL (15-min TTL) |
| `/api/compliance-check` | POST | 5/min, 30/day | Run SOC2/GDPR/PIPL compliance analysis on FlowZap Code. Returns frameworks + shareable result URL (60-min TTL). Backed by Deepseek LLM. |

---

## 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` | `label="Text"` instead of `label:"Text"` | Use colon for node attributes |
| `WRONG_EDGE_LABEL_SYNTAX` | `[label:"Text"]` instead of `[label="Text"]` | Use equals for edge labels |
| `ORPHAN_NODE` | Node 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

### Sequence Diagram Best Practices

FlowZap Code renders as both Workflow and Sequence views. The Sequence view draws messages top-to-bottom in **edge definition order**. Follow these rules for clean sequence diagrams:

- **Request-response pairing** — Every cross-lane request must have a corresponding return edge before the next major request begins
- **Chronological edge ordering** — Define edges in time order; sequence view uses definition order, not node IDs
- **Ping-pong rhythm** — In multi-lane sequence code, alternate request, response, then next request
- **No orphaned nodes** — Every node must participate in at least one edge
- **Separate async flows** — Define main-flow edges first, then background/async edges; never interleave

**Do:**
```
Client { # Client
n1: rectangle label:"Send request"
n2: rectangle label:"Receive response"
n1.handle(bottom) -> Server.n3.handle(top) [label="HTTP GET"]
}
Server { # Server
n3: rectangle label:"Process request"
n4: rectangle label:"Return data"
n3.handle(right) -> n4.handle(left)
n4.handle(top) -> Client.n2.handle(bottom) [label="200 OK"]
}
```

**Don't** (missing response, orphaned `n2`):
```
Client { # Client
n1: rectangle label:"Send request"
n2: rectangle label:"Receive response"
n1.handle(bottom) -> Server.n3.handle(top) [label="HTTP GET"]
}
Server { # Server
n3: rectangle label:"Process request"
n4: rectangle label:"Return data"
n3.handle(right) -> n4.handle(left)
}
```

---

## Complete Example

```
sales { # Sales Team
  n1: circle label:"Order Received"
  n2: rectangle label:"Submit 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

### Step 1: Learn Syntax
```json
{"name": "flowzap_get_syntax", "arguments": {}}
```

### Step 2: Generate Code
Based on user request, generate FlowZap Code following the syntax rules.

### Step 3: Validate
```json
{"name": "flowzap_validate", "arguments": {"code": "..."}}
```

### Step 4: Fix Errors (if any)
Parse error messages and correct the code.

### Step 5: Create Playground
```json
{"name": "flowzap_create_playground", "arguments": {"code": "..."}}
```

### 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 {\n  # 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` |
| Nested lanes | Lane inside lane | Flatten structure |
| Comments anywhere | `# comment` mid-lane | Only after `{` on same line |

---

## API Endpoints (Direct Access)

For agents that prefer direct HTTP calls instead of MCP:

### POST /api/validate

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

**Request:**
```json
{
  "code": "process { # P n1: circle label:\"Start\" }"
}
```

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

**Rate Limit:** 30 requests/minute per IP

### POST /api/playground/create

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

**Request:**
```json
{
  "code": "process { # P n1: circle label:\"Start\" }",
  "view": "workflow"
}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `code` | string | No | FlowZap Code to load |
| `view` | string | No | View mode: `workflow`, `sequence`, or `architecture` |

**Response:**
```json
{
  "success": true,
  "url": "https://flowzap.xyz/playground/abc123?view=architecture",
  "tokenExpiresAt": "2026-02-04T12:00:00.000Z"
}
```

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

---

## 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`:<br>**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`<br>**Windows:** `%APPDATA%\Claude\claude_desktop_config.json` |
| **Claude Code** | Run: `claude mcp add --transport stdio flowzap -- npx -y flowzap-mcp`<br>Or 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`:<br>`[mcp_servers.flowzap]`<br>`command = "npx"`<br>`args = ["-y", "flowzap-mcp"]`<br>Or run: `codex mcp add flowzap -- npx -y flowzap-mcp` |
| **Warp Terminal** | Settings → MCP Servers → Click "+ Add" → Paste the JSON config. |
| **Zed Editor** | Add to `settings.json`:<br>`{"context_servers": {"flowzap": {"command": "npx", "args": ["-y", "flowzap-mcp"]}}}` |
| **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:<br>`name: FlowZap`<br>`mcpServers:`<br>`  - name: flowzap`<br>`    command: npx`<br>`    args: ["-y", "flowzap-mcp"]` |
| **Sourcegraph Cody** | Add to VS Code `settings.json` via `openctx.providers` configuration. |

> **Not Compatible:** Replit and Lovable.dev only support remote MCP servers via URL. They cannot use the FlowZap MCP npm package directly. Use the [Public API](https://flowzap.xyz/api/playground/create) instead.

### JSON Configuration

All tools use the same JSON configuration format:

```json
{
  "mcpServers": {
    "flowzap": {
      "command": "npx",
      "args": ["-y", "flowzap-mcp"]
    }
  }
}
```

> **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`

---

## Support & Resources

- **Syntax Documentation:** https://flowzap.xyz/flowzap-code
- **Interactive Playground:** https://flowzap.xyz/playground
- **Template Library:** https://flowzap.xyz/templates
- **GitHub:** https://github.com/flowzap-xyz/flowzap-mcp
- **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

### Install as Agent Skill

Install the FlowZap skill for 40+ compatible coding agents via [skills.sh](https://skills.sh):

```bash
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.4.3 | May 2026 | Strengthened tool descriptions so all MCP clients auto-invoke `flowzap_compliance_check` with `flowzap_create_playground` on compliance requests; result page layout aligned with manual checker |
| 1.4.2 | May 2026 | Shareable ephemeral compliance result URLs (60-min TTL, noindex); SKILL.md enforces two-line response format |
| 1.4.1 | May 2026 | Compliance check returns `resultUrl` alongside Markdown report |
| 1.4.0 | May 2026 | New `flowzap_compliance_check` tool (SOC2/GDPR/PIPL, Deepseek-backed) with strict 3-layer rate limits; cross-sell hint added to `flowzap_create_playground`; 8 tools total |
| 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 https://flowzap.xyz/docs*