{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"FlowZap MCP Server Documentation","version":"1.4.3","lastUpdated":"2026-05-25","targetAudience":["LLMs","AI Agents","Agentic Systems"],"urls":{"capabilitiesManifest":"https://flowzap.xyz/.well-known/capabilities.json","documentation":"https://flowzap.xyz/docs/mcp","markdown":"https://flowzap.xyz/docs/mcp.md","json":"https://flowzap.xyz/docs/mcp.json","syntaxSpec":"https://flowzap.xyz/flowzap-code","playground":"https://flowzap.xyz/playground","templates":"https://flowzap.xyz/templates","npmPackage":"https://www.npmjs.com/package/flowzap-mcp","agentSkill":"https://skills.sh/flowzap-xyz/flowzap-mcp/flowzap-diagrams","skillSource":"https://github.com/flowzap-xyz/flowzap-mcp/tree/main/skills/flowzap-diagrams","usageStats":"https://flowzap.xyz/.well-known/flowzap-stats.json","serverCard":"https://flowzap.xyz/.well-known/mcp/server-card.json"},"overview":{"description":"The FlowZap MCP Server enables AI agents to create, validate, and share professional Workflow, Sequence and Architecture diagrams using FlowZap Code.","keyFeatures":["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"]},"installation":{"compatibleTools":[{"name":"Claude Desktop","configFile":{"macOS":"~/Library/Application Support/Claude/claude_desktop_config.json","windows":"%APPDATA%\\Claude\\claude_desktop_config.json"},"howToConfigure":"Add to claude_desktop_config.json"},{"name":"Claude Code","command":"claude mcp add --transport stdio flowzap -- npx -y flowzap-mcp","alternativeConfigFile":".mcp.json","howToConfigure":"Run CLI command or add to .mcp.json in project root"},{"name":"Cursor","howToConfigure":"Open Settings → Features → MCP Servers → Add Server. Use same JSON config."},{"name":"Windsurf IDE","configFile":"~/.codeium/windsurf/mcp_config.json","howToConfigure":"Add to ~/.codeium/windsurf/mcp_config.json"},{"name":"OpenAI Codex","configFile":"~/.codex/config.toml","command":"codex mcp add flowzap -- npx -y flowzap-mcp","tomlConfig":"[mcp_servers.flowzap]\\ncommand = \"npx\"\\nargs = [\"-y\", \"flowzap-mcp\"]","howToConfigure":"Add to ~/.codex/config.toml or run CLI command"},{"name":"Warp Terminal","howToConfigure":"Settings → MCP Servers → Click '+ Add' → Paste JSON config"},{"name":"Zed Editor","configFile":"settings.json","jsonConfig":"{\"context_servers\": {\"flowzap\": {\"command\": \"npx\", \"args\": [\"-y\", \"flowzap-mcp\"]}}}","howToConfigure":"Add to settings.json under context_servers"},{"name":"Cline (VS Code)","configFile":"cline_mcp_settings.json","howToConfigure":"Open Cline sidebar → MCP Servers icon → Edit cline_mcp_settings.json"},{"name":"Roo Code (VS Code)","configFile":".roo/mcp.json","howToConfigure":"Add to .roo/mcp.json in project or global settings"},{"name":"Continue.dev","configFile":".continue/mcpServers/flowzap.yaml","yamlConfig":"name: FlowZap\\nmcpServers:\\n  - name: flowzap\\n    command: npx\\n    args: [\"-y\", \"flowzap-mcp\"]","howToConfigure":"Create .continue/mcpServers/flowzap.yaml"},{"name":"Sourcegraph Cody","configFile":"settings.json","howToConfigure":"Add to VS Code settings.json via openctx.providers configuration"}],"notCompatible":[{"name":"Replit","reason":"Only supports remote MCP servers via URL (no STDIO)","alternative":"Use POST https://flowzap.xyz/api/playground/create"},{"name":"Lovable.dev","reason":"Only supports remote MCP servers via URL (no STDIO)","alternative":"Use POST https://flowzap.xyz/api/playground/create"}],"jsonConfig":{"mcpServers":{"flowzap":{"command":"npx","args":["-y","flowzap-mcp"]}}},"windowsNote":"If tools don't appear, use absolute path: C:\\\\Program Files\\\\nodejs\\\\npx.cmd. Find path with: where.exe npx"},"tools":[{"name":"flowzap_get_syntax","purpose":"Retrieve complete FlowZap Code syntax documentation","whenToUse":"Before generating any FlowZap Code, call this tool to learn the correct syntax","inputSchema":{"type":"object","properties":{},"required":[]},"output":"Complete syntax guide including global constraints, shape types, node syntax, edge syntax, loop syntax, and common mistakes"},{"name":"flowzap_validate","purpose":"Validate FlowZap Code syntax before creating a diagram","whenToUse":"Always validate code before calling flowzap_create_playground","inputSchema":{"type":"object","properties":{"code":{"type":"string","description":"FlowZap Code to validate"}},"required":["code"]},"output":{"success":"Stats with lanes, nodes, edges count","failure":"Line-by-line error messages with fixes"}},{"name":"flowzap_create_playground","purpose":"Create a shareable playground URL with the diagram","whenToUse":"After validation passes, create a playground for users to view and edit","inputSchema":{"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":"Shareable playground URL (expires after 15 minutes of inactivity)","notes":["Automatically validates code before creating playground","Returns validation errors if code is invalid","No authentication required to view","Use view='architecture' for system-level overview of multi-lane diagrams"]},{"name":"flowzap_export_graph","purpose":"Export FlowZap Code as structured JSON graph","whenToUse":"When you need to analyze diagram structure programmatically","inputSchema":{"type":"object","properties":{"code":{"type":"string","description":"FlowZap Code to parse"}},"required":["code"]},"output":"JSON with lanes, nodes, and edges arrays"},{"name":"flowzap_artifact_to_diagram","purpose":"Parse HTTP logs, OpenAPI specs, or code into FlowZap diagrams","whenToUse":"When converting technical artifacts into visual workflows","inputSchema":{"type":"object","properties":{"artifactType":{"type":"string","enum":["http_logs","openapi","code"],"description":"Type of artifact to parse"},"content":{"type":"string","description":"Raw artifact content"},"view":{"type":"string","enum":["workflow","sequence","architecture"],"description":"Preferred diagram view. Use architecture for system-level overview."}},"required":["artifactType","content"]},"output":"FlowZap Code and playground URL"},{"name":"flowzap_diff","purpose":"Compare two versions of FlowZap Code","whenToUse":"When explaining changes between diagram versions","inputSchema":{"type":"object","properties":{"oldCode":{"type":"string","description":"Original FlowZap Code"},"newCode":{"type":"string","description":"Updated FlowZap Code"}},"required":["oldCode","newCode"]},"output":"Structured diff showing added, removed, and updated elements"},{"name":"flowzap_apply_change","purpose":"Apply structured patch operations to FlowZap Code","whenToUse":"When making incremental changes to existing diagrams","inputSchema":{"type":"object","properties":{"code":{"type":"string","description":"Current FlowZap Code"},"operations":{"type":"array","description":"Patch operations to apply","items":{"type":"object","properties":{"op":{"type":"string","enum":["insertNode","removeNode","updateNode","insertEdge","removeEdge"]}}}}},"required":["code","operations"]},"output":"Updated FlowZap Code and playground URL"},{"name":"flowzap_compliance_check","purpose":"Run automated SOC2, GDPR, and PIPL compliance analysis on a FlowZap Code data-flow diagram","whenToUse":"When the user asks for a privacy, security, or regulatory review of a data-flow diagram. Backed by Deepseek LLM with strict rate limits.","inputSchema":{"type":"object","properties":{"code":{"type":"string","description":"FlowZap Code data-flow diagram to analyze","maxLength":50000},"lng":{"type":"string","enum":["en","fr","zh"],"description":"Response language (default: en)"}},"required":["code"]},"output":"Markdown audit report with risks, recommendations, and link to manual checker at https://flowzap.xyz/soc2-gdpr-pipl-compliance-checker","rateLimit":"3/day per IP, 1/hour burst, global 5-minute circuit breaker (Deepseek LLM cost protection)"}],"security":{"networkSecurity":{"ssrfPrevention":"Only connects to flowzap.xyz and www.flowzap.xyz via HTTPS","urlValidation":"All returned URLs are verified to originate from FlowZap domains","requestTimeout":"30 seconds"},"inputValidation":{"maxCodeLength":50000,"maxInputLength":100000,"nullByteRemoval":true,"controlCharacterSanitization":true},"rateLimiting":{"validate":{"maxRequests":30,"windowSeconds":60},"playground":{"maxRequests":5,"windowSeconds":60,"dailyLimit":50},"complianceCheck":{"dailyLimit":3,"hourlyBurstLimit":1,"globalCircuitBreakerSeconds":300,"scope":"per-IP or per-mcpIdentity","notes":"Only successful calls count toward quota. Backed by Deepseek LLM."}},"dataPrivacy":{"authenticationRequired":false,"userDataStored":false,"sessionTTL":"60 minutes","tracking":false,"cookies":false}},"syntax":{"globalConstraints":["UTF-8 plain text only (no emojis)","Node IDs: n1, n2, n3... (globally unique, sequential, no gaps)","Only 4 shapes: circle, rectangle, diamond, taskbox","Only 4 attributes: label, owner, description, system","Lane comment MUST be on same line as opening brace: 'laneName { # Label' (not on next line)","No Mermaid, PlantUML, or other DSL syntax","Sequence diagram quality: every cross-lane request must have a matching response edge before the next major request begins","Define edges in chronological order (sequence view uses definition order, not node IDs)","Use a ping-pong rhythm in multi-lane sequence code: 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"],"shapes":{"circle":"Start/End events","rectangle":"Tasks/Activities/Process steps","diamond":"Decision gateways","taskbox":"Assigned tasks with owner, description, system"},"nodeAttributeSyntax":"colon (label:\"Text\")","edgeLabelSyntax":"equals with brackets ([label=\"Text\"])","handleDirections":["left","right","top","bottom"],"crossLaneEdgeFormat":"laneName.nX.handle(direction)","loopFormat":"loop [condition] n1 n2 n3"},"validationErrors":[{"code":"CONTAINS_EMOJI","description":"Emoji characters detected","fix":"Use UTF-8 plain text only"},{"code":"NESTED_LANE","description":"Lane defined inside another lane","fix":"Flatten lane structure"},{"code":"UNMATCHED_BRACE","description":"Closing } without opening {","fix":"Check brace balance"},{"code":"UNCLOSED_BRACE","description":"Missing closing }","fix":"Add closing brace"},{"code":"DUPLICATE_NODE_ID","description":"Same node ID used twice","fix":"Use unique IDs: n1, n2, n3..."},{"code":"INVALID_SHAPE","description":"Unknown shape type","fix":"Use: circle, rectangle, diamond, taskbox"},{"code":"MISSING_LABEL","description":"Node without label (except taskbox)","fix":"Add label:\"Text\""},{"code":"NODE_OUTSIDE_LANE","description":"Node defined outside any lane","fix":"Move inside a lane block"},{"code":"MISSING_HANDLES","description":"Edge without handle syntax","fix":"Use n1.handle(right) -> n2.handle(left)"},{"code":"INVALID_EDGE_SYNTAX","description":"Malformed edge definition","fix":"Check arrow syntax ->"},{"code":"INVALID_DIRECTION","description":"Unknown handle direction","fix":"Use: left, right, top, bottom"},{"code":"EDGE_OUTSIDE_LANE","description":"Edge defined outside any lane","fix":"Move inside a lane block"},{"code":"UNDEFINED_LANE_REF","description":"Cross-lane ref to non-existent lane","fix":"Check lane name spelling"},{"code":"INVALID_LOOP_SYNTAX","description":"Malformed loop definition","fix":"Use loop [condition] n1 n2"},{"code":"LOOP_OUTSIDE_LANE","description":"Loop defined outside any lane","fix":"Move inside a lane block"},{"code":"MISPLACED_COMMENT","description":"Comment in wrong location","fix":"Put the only allowed comment on the same line as the lane opening brace"},{"code":"COMMENT_OUTSIDE_LANE","description":"Comment outside any lane","fix":"Remove it or move the display label onto the lane opening line"},{"code":"UNDEFINED_NODE","description":"Edge references undefined node","fix":"Define node before referencing"},{"code":"NON_SEQUENTIAL_NUMBERING","description":"Node numbering does not start at n1 or has a gap","fix":"Use n1, n2, n3... sequentially across the whole diagram"},{"code":"WRONG_LABEL_SYNTAX","description":"label=\"Text\" instead of label:\"Text\"","fix":"Use colon for node attributes"},{"code":"WRONG_EDGE_LABEL_SYNTAX","description":"[label:\"Text\"] instead of [label=\"Text\"]","fix":"Use equals for edge labels"},{"code":"ORPHAN_NODE","description":"Node not connected to any edge","fix":"Connect it as a source or target edge, or remove it"},{"code":"MISSING_RETURN_EDGE","description":"Cross-lane request has no corresponding return edge","fix":"Add a response edge from the target lane back to the source lane"},{"code":"MULTIPLE_OUTBOUND_REQUESTS","description":"A lane sends another cross-lane request before the prior one is answered","fix":"Use a strict request-response-next-request rhythm"},{"code":"CHRONOLOGICAL_PAIRING_VIOLATION","description":"A different cross-lane request appears before the previous return edge","fix":"Reorder edges to match the true request-response timeline"},{"code":"EMPTY_DIAGRAM","description":"No nodes defined","fix":"Add at least one node"},{"code":"WRONG_DSL_FORMAT","description":"Mermaid/PlantUML detected","fix":"Use FlowZap syntax only"}],"validationWarnings":[{"code":"NON_PRINTABLE_CHARS","description":"Control characters detected","recommendation":"Use plain text only"},{"code":"DUPLICATE_LANE","description":"Same lane defined twice","recommendation":"Merge into single block"},{"code":"MISSING_LANE_LABEL","description":"Lane without # Display Name","recommendation":"Add display label"},{"code":"NON_STANDARD_NODE_ID","description":"ID not in n1, n2, n3 format","recommendation":"Use standard numbering"},{"code":"TASKBOX_MISSING_PROPS","description":"Taskbox without owner/description","recommendation":"Add required properties"},{"code":"LOOP_TOO_FEW_NODES","description":"Loop with only 1 node","recommendation":"Include at least 2 nodes"},{"code":"UNKNOWN_ATTRIBUTE","description":"Non-standard attribute used","recommendation":"Use: label, owner, description, system"},{"code":"LABEL_TOO_LONG","description":"Label exceeds 50 characters","recommendation":"Keep labels concise"}],"recommendedWorkflow":[{"step":1,"action":"Learn Syntax","tool":"flowzap_get_syntax"},{"step":2,"action":"Generate Code","description":"Based on user request, generate FlowZap Code following the syntax rules"},{"step":3,"action":"Validate","tool":"flowzap_validate"},{"step":4,"action":"Fix Errors","description":"Parse error messages and correct the code"},{"step":5,"action":"Create Playground","tool":"flowzap_create_playground"},{"step":6,"action":"Present to User","description":"Share the playground URL with the user"}],"commonMistakes":[{"mistake":"Lane comment on separate line","incorrect":"laneName {\n  # Label","correct":"laneName { # Label"},{"mistake":"Abbreviated shapes","incorrect":"n1: rect","correct":"n1: rectangle"},{"mistake":"Missing handles","incorrect":"n1 -> n2","correct":"n1.handle(right) -> n2.handle(left)"},{"mistake":"Wrong node attribute syntax","incorrect":"label=\"Text\"","correct":"label:\"Text\""},{"mistake":"Wrong edge label syntax","incorrect":"[label:\"Text\"]","correct":"[label=\"Text\"]"},{"mistake":"Emojis in labels","incorrect":"label:\"Start 🚀\"","correct":"label:\"Start\""},{"mistake":"Unknown attributes","incorrect":"priority:\"high\"","correct":"(remove - not supported)"},{"mistake":"Non-sequential IDs","incorrect":"n1, n3, n5","correct":"n1, n2, n3"},{"mistake":"Undefined lane refs","incorrect":"undefined.n5","correct":"Use actual lane name"},{"mistake":"Missing response edge","incorrect":"Request from A to B with no return edge","correct":"Add return edge from B back to A"},{"mistake":"Second request before response","incorrect":"A -> B, then A -> C, then B -> A","correct":"A -> B, then B -> A, then next request"},{"mistake":"Orphaned node","incorrect":"Node defined but not in any edge","correct":"Connect node as source or target of an edge"},{"mistake":"Interleaved async flows","incorrect":"Main-flow and background edges mixed","correct":"Define all main-flow edges first, then async edges"}],"apiEndpoints":{"validate":{"url":"https://flowzap.xyz/api/validate","method":"POST","rateLimit":"30 requests/minute per IP","requestBody":{"code":"string"},"responseBody":{"valid":"boolean","errors":"array","warnings":"array","stats":{"lanes":"number","nodes":"number","edges":"number","loops":"number"}}},"playground":{"url":"https://flowzap.xyz/api/playground/create","method":"POST","rateLimit":"5 requests/minute, 50/day per IP","requestBody":{"code":"string (optional)","view":"string (optional: workflow|sequence|architecture)"},"responseBody":{"success":"boolean","url":"string","tokenExpiresAt":"ISO 8601 datetime"}},"complianceCheck":{"url":"https://flowzap.xyz/api/compliance-check","method":"POST","rateLimit":"5 requests/minute, 30/day per IP","requestBody":{"code":"string (required, max 50,000 chars)","lng":"string (optional: en|fr|zh, default: en)"},"responseBody":{"frameworks":"object (gdpr, soc2, pipl with findings arrays)","resultUrl":"string (shareable ephemeral URL, 60-min TTL)","tokenExpiresAt":"ISO 8601 datetime","disclaimer":"string"}}},"examples":{"simpleProcess":"process {\n  # Process\n  n1: circle label:\"Start\"\n  n2: rectangle label:\"Step\"\n  n3: circle label:\"End\"\n  n1.handle(right) -> n2.handle(left)\n  n2.handle(right) -> n3.handle(left)\n}","multiLane":"sales {\n  # Sales Team\n  n1: circle label:\"Order Received\"\n  n2: rectangle label:\"Validate Order\"\n  n3: diamond label:\"Valid?\"\n  n1.handle(right) -> n2.handle(left)\n  n2.handle(right) -> n3.handle(left)\n  n3.handle(right) -> fulfillment.n4.handle(left) [label=\"Yes\"]\n  n3.handle(bottom) -> n6.handle(top) [label=\"No\"]\n  n6: rectangle label:\"Reject Order\"\n}\n\nfulfillment {\n  # Fulfillment\n  n4: rectangle label:\"Process Order\"\n  n5: circle label:\"Complete\"\n  n4.handle(right) -> n5.handle(left)\n}"},"discovery":{"humanDocs":"https://flowzap.xyz/docs/mcp","machineDocs":"https://flowzap.xyz/docs/mcp.json","markdown":"https://flowzap.xyz/docs/mcp.md","capabilities":"https://flowzap.xyz/.well-known/capabilities.json","serverCard":"https://flowzap.xyz/.well-known/mcp/server-card.json","usageStats":"https://flowzap.xyz/.well-known/flowzap-stats.json","officialRegistry":"https://registry.modelcontextprotocol.io/?q=flowzap","smitheryServer":"https://smithery.ai/server/@flowzap/flowzap","smitherySkill":"https://smithery.ai/skills/Flowzap/diagram-skill","pulseMcp":"https://www.pulsemcp.com/servers/flowzap","glama":"https://glama.ai/mcp/servers/flowzap-xyz/flowzap-mcp","mcpServersOrg":"https://mcpservers.org/servers/flowzap-xyz-docs-mcp","aiBase":"https://mcp.aibase.com/server/1639702939289526535","skillsSh":"https://skills.sh/flowzap-xyz/flowzap-mcp/flowzap-diagrams","huggingFaceDataset":"https://huggingface.co/datasets/Jules-OC/flowzap-sequence-workflows/tree/main"}}