Builder API - MCP Server with LangGraph

Overview

The Builder API provides endpoints for creating, managing, and deploying visual workflows. All endpoints (except health and static assets) require JWT authentication.

Base URL

# Development
http://localhost:8001

# Test Infrastructure
http://localhost:9001

# Production
https://builder.yourdomain.com

Authentication

All API endpoints (except /health and static assets) require JWT authentication:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Health Endpoints

GET /api/builder/health

Health check endpoint (no authentication required). Response:

{
  "status": "healthy",
  "version": "1.0.0"
}

Status Codes:

200

Success

Service is healthy

GET /

Serves the React SPA frontend (no authentication required). Response: HTML content with React application.

Workflow Endpoints

POST /api/builder/workflows

Create a new workflow.

name

string

required

Display name for the workflow

description

string

Optional description

nodes

array

required

List of workflow nodes

edges

array

required

List of connections between nodes

Request:

curl -X POST http://localhost:9001/api/builder/workflows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Multi-agent support workflow",
    "nodes": [
      {"id": "start", "type": "start", "position": {"x": 100, "y": 100}},
      {"id": "agent", "type": "agent", "position": {"x": 300, "y": 100}, "data": {"name": "Support", "prompt": "You are helpful"}},
      {"id": "end", "type": "end", "position": {"x": 500, "y": 100}}
    ],
    "edges": [
      {"id": "e1", "source": "start", "target": "agent"},
      {"id": "e2", "source": "agent", "target": "end"}
    ]
  }'

Response:

{
  "id": "wf_abc123def456",
  "name": "Customer Support Agent",
  "description": "Multi-agent support workflow",
  "version": 1,
  "created_at": "2025-12-06T10:00:00Z",
  "updated_at": "2025-12-06T10:00:00Z",
  "created_by": "alice",
  "nodes": [...],
  "edges": [...]
}

Status Codes:

201

Created

Workflow created successfully

400

Bad Request

Invalid workflow definition

401

Unauthorized

Invalid or missing authentication token

GET /api/builder/workflows

List all workflows for the authenticated user.

limit

integer

default:"20"

Maximum number of workflows to return

offset

integer

default:"0"

Number of workflows to skip for pagination

tag

string

Filter by tag

Request:

curl "http://localhost:9001/api/builder/workflows?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  {
    "id": "wf_abc123def456",
    "name": "Customer Support Agent",
    "description": "Multi-agent support workflow",
    "version": 3,
    "created_at": "2025-12-01T10:00:00Z",
    "updated_at": "2025-12-06T10:00:00Z",
    "node_count": 5,
    "tags": ["support", "production"]
  },
  {
    "id": "wf_xyz789",
    "name": "Data Pipeline",
    "description": "ETL workflow",
    "version": 1,
    "created_at": "2025-12-05T09:00:00Z",
    "updated_at": "2025-12-05T09:00:00Z",
    "node_count": 3,
    "tags": ["data"]
  }
]

GET /api/builder/workflows/

Get details for a specific workflow. Path Parameters:

workflow_id

string

required

The workflow ID

Request:

curl http://localhost:9001/api/builder/workflows/wf_abc123def456 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": "wf_abc123def456",
  "name": "Customer Support Agent",
  "description": "Multi-agent support workflow",
  "version": 3,
  "created_at": "2025-12-01T10:00:00Z",
  "updated_at": "2025-12-06T10:00:00Z",
  "created_by": "alice",
  "nodes": [
    {
      "id": "start",
      "type": "start",
      "position": {"x": 100, "y": 100}
    },
    {
      "id": "agent",
      "type": "agent",
      "position": {"x": 300, "y": 100},
      "data": {
        "name": "Support",
        "prompt": "You are a helpful customer support agent..."
      }
    },
    {
      "id": "end",
      "type": "end",
      "position": {"x": 500, "y": 100}
    }
  ],
  "edges": [
    {"id": "e1", "source": "start", "target": "agent"},
    {"id": "e2", "source": "agent", "target": "end"}
  ],
  "metadata": {
    "tags": ["support", "production"],
    "deployed": true,
    "deployed_at": "2025-12-05T14:00:00Z"
  }
}

Status Codes:

200

Success

Workflow retrieved successfully

404

Not Found

Workflow does not exist or user lacks access

PUT /api/builder/workflows/

Update an existing workflow. Request:

curl -X PUT http://localhost:9001/api/builder/workflows/wf_abc123def456 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent v2",
    "nodes": [...],
    "edges": [...]
  }'

Response:

{
  "id": "wf_abc123def456",
  "name": "Customer Support Agent v2",
  "version": 4,
  "updated_at": "2025-12-06T11:00:00Z"
}

Status Codes:

200

Success

Workflow updated successfully

404

Not Found

Workflow does not exist

DELETE /api/builder/workflows/

Delete a workflow. Request:

curl -X DELETE http://localhost:9001/api/builder/workflows/wf_abc123def456 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "message": "Workflow deleted successfully"
}

Status Codes:

204

No Content

Workflow deleted successfully

404

Not Found

Workflow does not exist

Validation Endpoints

POST /api/builder/validate

Validate a workflow definition without saving.

nodes

array

required

List of workflow nodes

edges

array

required

List of connections between nodes

Request:

curl -X POST http://localhost:9001/api/builder/validate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {"id": "start", "type": "start"},
      {"id": "agent", "type": "agent", "data": {"name": "Test"}},
      {"id": "end", "type": "end"}
    ],
    "edges": [
      {"source": "start", "target": "agent"},
      {"source": "agent", "target": "end"}
    ]
  }'

Response (Valid):

{
  "valid": true,
  "errors": [],
  "warnings": []
}

Response (Invalid):

{
  "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": "error"
    }
  ],
  "warnings": [
    {
      "type": "EMPTY_PROMPT",
      "message": "Agent 'agent_2' has no system prompt configured",
      "node_id": "agent_2",
      "severity": "warning"
    }
  ]
}

Validation Rules:

Rule	Severity	Description
`MISSING_START_NODE`	error	No Start node found
`MULTIPLE_START_NODES`	error	More than one Start node
`MISSING_END_NODE`	error	No End node found
`ORPHAN_NODE`	error	Node not connected to workflow
`UNREACHABLE_END`	error	End node not reachable from Start
`CYCLE_DETECTED`	error	Circular reference without exit
`DUPLICATE_NODE_ID`	error	Same ID used for multiple nodes
`EMPTY_PROMPT`	warning	Agent has no system prompt
`UNUSED_EDGE`	warning	Edge connects invalid nodes

Code Generation Endpoints

POST /api/builder/generate

Generate LangGraph Python code from a workflow.

name

string

Name for the generated module

nodes

array

required

List of workflow nodes

edges

array

required

List of connections between nodes

options

object

Code generation options

Request:

curl -X POST http://localhost:9001/api/builder/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CustomerSupport",
    "nodes": [
      {"id": "start", "type": "start"},
      {"id": "agent", "type": "agent", "data": {"name": "Support", "prompt": "You are helpful"}},
      {"id": "end", "type": "end"}
    ],
    "edges": [
      {"source": "start", "target": "agent"},
      {"source": "agent", "target": "end"}
    ],
    "options": {
      "include_types": true,
      "include_docstrings": true
    }
  }'

Response:

{
  "code": "\"\"\"\\nGenerated workflow: CustomerSupport\\n...\\n\"\"\"\\n\\nfrom typing import TypedDict\\nfrom langgraph.graph import StateGraph, START, END\\n\\n\\nclass AgentState(TypedDict):\\n    messages: list\\n\\n\\ndef support(state: AgentState) -> AgentState:\\n    \\\"\\\"\\\"Support agent node.\\\"\\\"\\\"\\n    return state\\n\\n\\nworkflow = StateGraph(AgentState)\\nworkflow.add_node(\\\"support\\\", support)\\nworkflow.add_edge(START, \\\"support\\\")\\nworkflow.add_edge(\\\"support\\\", END)\\n\\napp = workflow.compile()\\n",
  "filename": "customer_support.py",
  "language": "python",
  "dependencies": [
    "langgraph>=1.0.0",
    "langchain-core>=0.3.0"
  ]
}

Generation Options:

Option	Type	Default	Description
`include_types`	boolean	`true`	Generate TypedDict state classes
`include_docstrings`	boolean	`true`	Add docstrings to functions
`include_mcp_tools`	boolean	`true`	Generate MCP tool imports
`checkpoint_config`	boolean	`false`	Include checkpointing setup
`async_mode`	boolean	`false`	Generate async functions

MCP Integration Endpoints

GET /api/builder/tools

List available MCP tools for workflow integration. Request:

curl http://localhost:9001/api/builder/tools \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  {
    "name": "web_search",
    "description": "Search the web for information",
    "parameters": {
      "query": {"type": "string", "required": true},
      "max_results": {"type": "integer", "default": 10}
    }
  },
  {
    "name": "calculator",
    "description": "Perform mathematical calculations",
    "parameters": {
      "expression": {"type": "string", "required": true}
    }
  }
]

GET /api/builder/resources

List available MCP resources. Request:

curl http://localhost:9001/api/builder/resources \
  -H "Authorization: Bearer $TOKEN"

Response:

[
  {
    "uri": "file:///data/knowledge_base.txt",
    "name": "Knowledge Base",
    "mimeType": "text/plain"
  },
  {
    "uri": "db://customers",
    "name": "Customer Database",
    "mimeType": "application/json"
  }
]

Version History Endpoints

GET /api/builder/workflows//versions

List version history for a workflow. Request:

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

Response:

[
  {
    "version": 3,
    "created_at": "2025-12-06T10:00:00Z",
    "created_by": "alice",
    "message": "Added billing agent"
  },
  {
    "version": 2,
    "created_at": "2025-12-05T14:00:00Z",
    "created_by": "alice",
    "message": "Updated prompts"
  },
  {
    "version": 1,
    "created_at": "2025-12-01T10:00:00Z",
    "created_by": "alice",
    "message": "Initial version"
  }
]

GET /api/builder/workflows//versions/

Get a specific version of a workflow. Request:

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

POST /api/builder/workflows//rollback

Rollback to a previous version.

version

integer

required

Version number to rollback to

Request:

curl -X POST http://localhost:9001/api/builder/workflows/wf_abc123/rollback \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 2}'

Response:

{
  "id": "wf_abc123",
  "version": 4,
  "message": "Rolled back to version 2"
}

Error Responses

All endpoints may return the following errors:

400 Bad Request

{
  "error": "bad_request",
  "message": "Invalid workflow definition",
  "details": [
    {"field": "nodes", "error": "must not be empty"}
  ],
  "code": "INVALID_WORKFLOW"
}

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or expired token",
  "code": "AUTH_INVALID_TOKEN"
}

403 Forbidden

{
  "error": "forbidden",
  "message": "Access denied to this workflow",
  "code": "AUTH_ACCESS_DENIED"
}

404 Not Found

{
  "error": "not_found",
  "message": "Workflow not found",
  "code": "WORKFLOW_NOT_FOUND"
}

422 Unprocessable Entity

{
  "error": "validation_error",
  "message": "Workflow validation failed",
  "details": {
    "valid": false,
    "errors": [...]
  },
  "code": "VALIDATION_FAILED"
}

Node Type Reference

Start Node

{
  "id": "start",
  "type": "start",
  "position": {"x": 100, "y": 100}
}

Agent Node

{
  "id": "agent_1",
  "type": "agent",
  "position": {"x": 300, "y": 100},
  "data": {
    "name": "AssistantAgent",
    "prompt": "You are a helpful assistant...",
    "model": "gemini-2.5-flash",
    "tools": ["web_search", "calculator"],
    "temperature": 0.7
  }
}

Router Node

{
  "id": "router_1",
  "type": "router",
  "position": {"x": 500, "y": 100},
  "data": {
    "conditions": [
      {"label": "billing", "pattern": "billing|payment|invoice"},
      {"label": "technical", "pattern": "error|bug|issue"},
      {"label": "default", "pattern": ".*"}
    ]
  }
}

Tool Node

{
  "id": "tool_1",
  "type": "tool",
  "position": {"x": 700, "y": 100},
  "data": {
    "tool_name": "web_search",
    "arguments": {
      "query": "{{state.query}}",
      "max_results": 5
    }
  }
}

Human Node

{
  "id": "human_1",
  "type": "human",
  "position": {"x": 900, "y": 100},
  "data": {
    "prompt": "Please review this response:",
    "timeout": 3600,
    "options": ["approve", "reject", "revise"]
  }
}

End Node

{
  "id": "end",
  "type": "end",
  "position": {"x": 1100, "y": 100},
  "data": {
    "output": "state.messages[-1]"
  }
}

SDK Examples

Python

import httpx

class BuilderClient:
    def __init__(self, base_url: str, token: str):
        self.client = httpx.Client(
            base_url=base_url,
            headers={"Authorization": f"Bearer {token}"}
        )

    def create_workflow(self, name: str, nodes: list, edges: list) -> dict:
        response = self.client.post(
            "/api/builder/workflows",
            json={"name": name, "nodes": nodes, "edges": edges}
        )
        response.raise_for_status()
        return response.json()

    def validate(self, nodes: list, edges: list) -> dict:
        response = self.client.post(
            "/api/builder/validate",
            json={"nodes": nodes, "edges": edges}
        )
        return response.json()

    def generate_code(self, name: str, nodes: list, edges: list) -> str:
        response = self.client.post(
            "/api/builder/generate",
            json={"name": name, "nodes": nodes, "edges": edges}
        )
        return response.json()["code"]

# Usage
client = BuilderClient("http://localhost:9001", token)

nodes = [
    {"id": "start", "type": "start"},
    {"id": "agent", "type": "agent", "data": {"name": "Helper", "prompt": "Be helpful"}},
    {"id": "end", "type": "end"}
]
edges = [
    {"source": "start", "target": "agent"},
    {"source": "agent", "target": "end"}
]

# Validate first
result = client.validate(nodes, edges)
if result["valid"]:
    # Create workflow
    workflow = client.create_workflow("My Workflow", nodes, edges)
    print(f"Created: {workflow['id']}")

    # Generate code
    code = client.generate_code("my_workflow", nodes, edges)
    print(code)

JavaScript/TypeScript

class BuilderClient {
  private baseUrl: string;
  private token: string;

  constructor(baseUrl: string, token: string) {
    this.baseUrl = baseUrl;
    this.token = token;
  }

  private async request(path: string, options: RequestInit = {}): Promise<Response> {
    return fetch(`${this.baseUrl}${path}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
  }

  async createWorkflow(name: string, nodes: Node[], edges: Edge[]): Promise<Workflow> {
    const response = await this.request('/api/builder/workflows', {
      method: 'POST',
      body: JSON.stringify({ name, nodes, edges })
    });
    return response.json();
  }

  async validate(nodes: Node[], edges: Edge[]): Promise<ValidationResult> {
    const response = await this.request('/api/builder/validate', {
      method: 'POST',
      body: JSON.stringify({ nodes, edges })
    });
    return response.json();
  }

  async generateCode(name: string, nodes: Node[], edges: Edge[]): Promise<string> {
    const response = await this.request('/api/builder/generate', {
      method: 'POST',
      body: JSON.stringify({ name, nodes, edges })
    });
    const data = await response.json();
    return data.code;
  }
}

// Usage
const client = new BuilderClient('http://localhost:9001', token);

const nodes = [
  { id: 'start', type: 'start' },
  { id: 'agent', type: 'agent', data: { name: 'Helper', prompt: 'Be helpful' }},
  { id: 'end', type: 'end' }
];

const edges = [
  { source: 'start', target: 'agent' },
  { source: 'agent', target: 'end' }
];

const result = await client.validate(nodes, edges);
if (result.valid) {
  const code = await client.generateCode('my_workflow', nodes, edges);
  console.log(code);
}

Builder Guide

Learn how to use the builder

Authentication API

Authentication endpoints

LangGraph Concepts

Understand LangGraph fundamentals

MCP Tools

Configure MCP tools

Full API access! Use these endpoints to programmatically manage workflows and integrate with your development pipeline.

API Documentation

Developer Tools

MCP Protocol

​Overview

​Base URL

​Authentication

​Health Endpoints

​GET /api/builder/health

​GET /

​Workflow Endpoints

​POST /api/builder/workflows

​GET /api/builder/workflows

​GET /api/builder/workflows/

​PUT /api/builder/workflows/

​DELETE /api/builder/workflows/

​Validation Endpoints

​POST /api/builder/validate

​Code Generation Endpoints

​POST /api/builder/generate

​MCP Integration Endpoints

​GET /api/builder/tools

​GET /api/builder/resources

​Version History Endpoints

​GET /api/builder/workflows//versions

​GET /api/builder/workflows//versions/

​POST /api/builder/workflows//rollback

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

​Node Type Reference

​Start Node

​Agent Node

​Router Node

​Tool Node

​Human Node

​End Node

​SDK Examples

​Python

​JavaScript/TypeScript

​Related Documentation

Builder Guide

Authentication API

LangGraph Concepts

MCP Tools

Overview

Base URL

Authentication

Health Endpoints

GET /api/builder/health

GET /

Workflow Endpoints

POST /api/builder/workflows

GET /api/builder/workflows

GET /api/builder/workflows/

PUT /api/builder/workflows/

DELETE /api/builder/workflows/

Validation Endpoints

POST /api/builder/validate

Code Generation Endpoints

POST /api/builder/generate

MCP Integration Endpoints

GET /api/builder/tools

GET /api/builder/resources

Version History Endpoints

GET /api/builder/workflows//versions

GET /api/builder/workflows//versions/

POST /api/builder/workflows//rollback

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

Node Type Reference

Start Node

Agent Node

Router Node

Tool Node

Human Node

End Node

SDK Examples

Python

JavaScript/TypeScript

Related Documentation