Visual Workflow Builder - MCP Server with LangGraph

Overview

The Visual Workflow Builder enables you to design AI agent workflows through an intuitive drag-and-drop interface. Build complex multi-agent systems without writing code, then generate production-ready LangGraph Python code.

Quick Start

Build your first workflow in minutes

API Reference

Explore the Builder API

Key Features

Drag-and-Drop Interface

Visual node-based editor
React Flow integration for smooth interactions
Real-time connection validation
Auto-layout for clean workflows

Code Generation

Generate production-ready LangGraph Python code
Export as standalone modules
Include type hints and docstrings
MCP tool integration ready

Workflow Validation

Real-time validation as you build
Graph connectivity checks
Node configuration validation
Error highlighting with suggestions

One-Click Deploy

Deploy workflows to MCP Server
Version control for workflows
Rollback capabilities
Environment-specific configurations

Architecture

Quick Start

Prerequisites

Docker and Docker Compose
Modern web browser (Chrome, Firefox, Safari, Edge)
Valid authentication credentials

Starting the Builder

Docker Compose
Development Mode

# Start full infrastructure including builder
make test-infra-full-up

# Access the builder
open http://localhost:13000

# Start the backend
uv run uvicorn src.mcp_server_langgraph.builder.api.server:app \
  --host 0.0.0.0 \
  --port 8001

# Start the frontend (in another terminal)
cd builder-frontend
npm install
npm run dev

Building Your First Workflow

Create New Workflow

Click “New Workflow” and give it a name like “Customer Support Agent”.

Add a Start Node

Drag a Start node from the palette onto the canvas. This is the entry point.

Add an Agent Node

Drag an Agent node and connect it to the Start node. Configure:

Name: CustomerSupport
Prompt: “You are a helpful customer support agent…”

Add Conditional Routing

Add a Router node to direct conversations based on intent:

Connect Agent → Router
Configure conditions: “billing”, “technical”, “general”

Add Specialized Agents

Add more Agent nodes for each route:

BillingAgent
TechnicalAgent
GeneralAgent

Add End Node

Connect all paths to an End node to complete the workflow.

Validate and Generate

Click “Validate” to check your workflow, then “Generate Code” to export.

Node Types

Start Node

Entry point for the workflow. Every workflow must have exactly one Start node.

Properties:
  - type: start
  - id: Unique identifier
  - position: {x, y} coordinates

Agent Node

An LLM-powered agent that processes messages.

Properties:
  - type: agent
  - name: Display name
  - prompt: System prompt for the agent
  - model: LLM model to use (optional)
  - tools: List of MCP tools to enable (optional)

Router Node

Conditional branching based on content or metadata.

Properties:
  - type: router
  - conditions: List of routing conditions
  - default: Default route if no conditions match

Tool Node

Execute an MCP tool directly in the workflow.

Properties:
  - type: tool
  - tool_name: Name of the MCP tool
  - arguments: Tool arguments (static or dynamic)

Human-in-the-Loop Node

Pause for human review or input.

Properties:
  - type: human
  - prompt: Message to show reviewer
  - timeout: Maximum wait time
  - options: Available response options

End Node

Termination point for the workflow. Multiple End nodes are allowed.

Properties:
  - type: end
  - output: Final output configuration

Workflow Examples

Simple Q&A Bot

Use Case: Basic question-answering with a single agent.

Multi-Stage Pipeline

Use Case: Process requests through multiple specialized agents.

Human-in-the-Loop Review

Use Case: Content generation with human approval.

Validation Rules

The builder validates workflows against these rules:

Rule	Description
Single Start	Exactly one Start node required
Reachable End	All paths must lead to an End node
No Orphans	All nodes must be connected
No Cycles	Workflow must be a DAG (no loops without Exit condition)
Valid Configs	All node configurations must be complete
Unique IDs	All node IDs must be unique

Validation Errors

When validation fails, the builder highlights problematic nodes:

{
  "valid": false,
  "errors": [
    {
      "type": "MISSING_END_NODE",
      "message": "Workflow must have at least one End node",
      "severity": "error"
    },
    {
      "type": "ORPHAN_NODE",
      "message": "Node 'agent_3' is not connected to the workflow",
      "node_id": "agent_3",
      "severity": "warning"
    }
  ]
}

Code Generation

Generated Code Structure

The builder generates production-ready LangGraph code:

"""
Generated workflow: Customer Support Agent
Created: 2025-12-06T10:30:00Z
"""

from typing import TypedDict
from langgraph.graph import StateGraph, START, END


class AgentState(TypedDict):
    messages: list
    current_intent: str | None


def customer_support(state: AgentState) -> AgentState:
    """Customer support agent node."""
    # Agent implementation
    return state


def router(state: AgentState) -> str:
    """Route based on detected intent."""
    intent = state.get("current_intent")
    if intent == "billing":
        return "billing_agent"
    elif intent == "technical":
        return "technical_agent"
    return "general_agent"


def billing_agent(state: AgentState) -> AgentState:
    """Billing specialist agent."""
    return state


def technical_agent(state: AgentState) -> AgentState:
    """Technical support agent."""
    return state


def general_agent(state: AgentState) -> AgentState:
    """General inquiry agent."""
    return state


# Build the graph
workflow = StateGraph(AgentState)

# Add nodes
workflow.add_node("customer_support", customer_support)
workflow.add_node("billing_agent", billing_agent)
workflow.add_node("technical_agent", technical_agent)
workflow.add_node("general_agent", general_agent)

# Add edges
workflow.add_edge(START, "customer_support")
workflow.add_conditional_edges(
    "customer_support",
    router,
    {
        "billing_agent": "billing_agent",
        "technical_agent": "technical_agent",
        "general_agent": "general_agent",
    }
)
workflow.add_edge("billing_agent", END)
workflow.add_edge("technical_agent", END)
workflow.add_edge("general_agent", END)

# Compile
app = workflow.compile()

Code Generation Options

Option	Description	Default
`include_types`	Generate TypedDict state classes	`true`
`include_docstrings`	Add docstrings to functions	`true`
`include_mcp_tools`	Generate MCP tool imports	`true`
`checkpoint_config`	Include checkpointing setup	`false`
`output_format`	Output format (python, module)	`python`

Workflow Storage

Workflows are stored with versioning support:

{
  "id": "wf_abc123",
  "name": "Customer Support Agent",
  "description": "Multi-agent customer support workflow",
  "version": 3,
  "created_at": "2025-12-01T10:00:00Z",
  "updated_at": "2025-12-06T10:30:00Z",
  "created_by": "alice",
  "nodes": [...],
  "edges": [...],
  "metadata": {
    "tags": ["support", "production"],
    "environment": "production"
  }
}

Version History

# List versions
curl http://localhost:9001/api/builder/workflows/wf_abc123/versions \
  -H "Authorization: Bearer $TOKEN"

# Get specific version
curl http://localhost:9001/api/builder/workflows/wf_abc123/versions/2 \
  -H "Authorization: Bearer $TOKEN"

# Rollback to version
curl -X POST http://localhost:9001/api/builder/workflows/wf_abc123/rollback \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"version": 2}'

Security

Authentication

All builder endpoints require JWT authentication:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Authorization

Workflow access is controlled by OpenFGA:

# Permission model
user:alice can create workflow:*
user:alice can edit workflow:wf_abc123
user:alice can deploy workflow:wf_abc123
user:bob can view workflow:wf_abc123  # Read-only access

# Team permissions
team:engineering can edit workflow:*
team:engineering can deploy workflow:*

Workflows may contain sensitive prompts and configurations. Ensure proper access controls before sharing.

API Endpoints

Endpoint	Method	Description
`/api/builder/workflows`	POST	Create new workflow
`/api/builder/workflows`	GET	List workflows
`/api/builder/workflows/{id}`	GET	Get workflow details
`/api/builder/workflows/{id}`	PUT	Update workflow
`/api/builder/workflows/{id}`	DELETE	Delete workflow
`/api/builder/validate`	POST	Validate workflow
`/api/builder/generate`	POST	Generate code
`/api/builder/health`	GET	Health check

See Builder API Reference for complete documentation.

Keyboard Shortcuts

Shortcut	Action
`Ctrl/Cmd + S`	Save workflow
`Ctrl/Cmd + Z`	Undo
`Ctrl/Cmd + Shift + Z`	Redo
`Delete`	Delete selected node
`Ctrl/Cmd + D`	Duplicate selected node
`Ctrl/Cmd + A`	Select all nodes
`Escape`	Deselect all
`Space + Drag`	Pan canvas
`Scroll`	Zoom in/out

Troubleshooting

Workflow won't save

Symptoms: Save button doesn’t respond or shows errorSolutions:

Check authentication token hasn’t expired
Validate workflow before saving (may have errors)
Check network connectivity to backend
Clear browser cache and reload

Code generation fails

Symptoms: Generated code is empty or incompleteSolutions:

Ensure workflow passes validation first
Check all agent prompts are configured
Verify node connections are complete
Check backend logs for detailed errors

Nodes won't connect

Symptoms: Can’t drag connections between nodesSolutions:

Check node types are compatible
Ensure you’re connecting output → input
Verify node isn’t already connected (single output only)
Try refreshing the page

Workflow won't deploy

Symptoms: Deploy button shows errorSolutions:

Validate workflow first
Check MCP Server is running
Verify deployment permissions
Check for conflicting workflow names

Best Practices

Start Simple

Begin with a linear workflow, then add complexity incrementally

Name Clearly

Use descriptive names for nodes and workflows

Validate Often

Run validation after each major change

Version Control

Save versions before major changes

Interactive Playground

Test your workflows in real-time

LangGraph Concepts

Understand LangGraph fundamentals

MCP Tools

Configure MCP tools

Deployment

Deploy workflows to production

Ready to build! Open the Visual Workflow Builder and start creating your first AI agent workflow.

​Overview

Quick Start

API Reference

​Key Features

​Architecture

​Quick Start

​Prerequisites

​Starting the Builder

​Building Your First Workflow

​Node Types

​Start Node

​Agent Node

​Router Node

​Tool Node

​Human-in-the-Loop Node

​End Node

​Workflow Examples

​Simple Q&A Bot

​Multi-Stage Pipeline

​Human-in-the-Loop Review

​Validation Rules

​Validation Errors

​Code Generation

​Generated Code Structure

​Code Generation Options

​Workflow Storage

​Version History

​Security

​Authentication

​Authorization

​API Endpoints

​Keyboard Shortcuts

​Troubleshooting

​Best Practices

Start Simple

Name Clearly

Validate Often

Version Control

​Related Documentation

Interactive Playground

LangGraph Concepts

MCP Tools

Deployment

Overview

Key Features

Architecture

Quick Start

Prerequisites

Starting the Builder

Building Your First Workflow

Node Types

Start Node

Agent Node

Router Node

Tool Node

Human-in-the-Loop Node

End Node

Workflow Examples

Simple Q&A Bot

Multi-Stage Pipeline

Human-in-the-Loop Review

Validation Rules

Validation Errors

Code Generation

Generated Code Structure

Code Generation Options

Workflow Storage

Version History

Security

Authentication

Authorization

API Endpoints

Keyboard Shortcuts

Troubleshooting

Best Practices

Related Documentation