@velaflows/mcp-server

MCP server for VelaFlows — AI-native access to 34 APIs, 464 workflow nodes, and 392 events.

What's Inside

| Capability | Count | Description | |------------|-------|-------------| | Tools | 22 | 8 reference lookup, 8 API proxy, 6 workflow builder | | Resources | 8 | Service catalog, node catalog, event catalog, guides, dynamic detail views | | Prompts | 6 | Build integrations, design workflows, debug errors, generate code, explain events, migrate webhooks |

Data is bundled at build time — no network calls needed for reference lookups:

• 34 OpenAPI specs covering 1,093 API endpoints across all VelaFlows microservices
• 464 workflow nodes across 9 categories with full config schemas
• 392 platform events across 32 categories (RabbitMQ routing keys, exchanges, descriptions)

Both local (stdio) and hosted (SSE) transport modes are supported.

Quick Start

Claude Code / Cursor (local stdio)

Add to your MCP config (.mcp.json, claude_desktop_config.json, or .cursor/mcp.json):

{
  "mcpServers": {
    "velaflows": {
      "command": "npx",
      "args": ["-y", "@velaflows/mcp-server"],
      "env": {
        "VELAFLOWS_API_TOKEN": "sk_live_your_token_here",
        "VELAFLOWS_WORKSPACE_ID": "your_workspace_id"
      }
    }
  }
}

Claude Desktop (remote SSE)

{
  "mcpServers": {
    "velaflows": {
      "url": "https://mcp.velaflows.com/sse",
      "headers": {
        "Authorization": "Bearer sk_live_your_token_here"
      }
    }
  }
}

Run Locally (development)

# stdio mode (default)
pnpm dev

# SSE mode
TRANSPORT=sse PORT=3100 pnpm dev

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | VELAFLOWS_API_TOKEN | For API tools | — | Your VelaFlows API token | | VELAFLOWS_WORKSPACE_ID | For API tools | — | Workspace ID for scoped requests | | VELAFLOWS_API_URL | No | https://api.velaflows.com/api/v1 | API base URL | | TRANSPORT | No | stdio | Transport mode: stdio or sse | | PORT | No | 3100 | Port for SSE mode |

Note: VELAFLOWS_API_TOKEN and VELAFLOWS_WORKSPACE_ID are only required for the 8 API proxy tools and 4 workflow builder tools that make live API calls. The 8 reference tools, 8 resources, and 6 prompts work entirely offline using bundled data.

Available Tools

Reference Tools (no auth required)

| Tool | Description | |------|-------------| | list-services | List all available VelaFlows API services with endpoint counts | | get-service-endpoints | List all API endpoints for a specific service | | get-endpoint-details | Get full details for a specific API endpoint including parameters, request body, and responses | | search-api | Search across all API endpoints by keyword (matches path, summary, description, tags) | | list-nodes | List all available workflow nodes, optionally filtered by category | | get-node-details | Get full details for a specific workflow node including config fields, help text, and examples | | list-events | List all platform events (RabbitMQ), optionally filtered by category | | search-events | Search platform events by keyword (matches type, label, category, description, exchange) |

API Proxy Tools (auth required)

| Tool | Description | |------|-------------| | api-get | Make an authenticated GET request to any VelaFlows API endpoint | | api-post | Make an authenticated POST request to any VelaFlows API endpoint | | api-patch | Make an authenticated PATCH request to any VelaFlows API endpoint | | api-delete | Make an authenticated DELETE request to any VelaFlows API endpoint | | list-workspaces | List all workspaces the authenticated user has access to | | get-current-user | Get the profile of the currently authenticated user | | list-conversations | List inbox conversations with optional filtering by status and limit | | list-leads | List CRM leads with optional filtering by pipeline, status, and limit |

Workflow Builder Tools (mixed auth)

| Tool | Description | |------|-------------| | create-workflow | Create a new workflow with a trigger and a sequence of nodes | | trigger-workflow | Manually trigger execution of an existing workflow | | list-workflows | List all workflows in the current workspace | | get-workflow-executions | Get recent executions for a specific workflow | | suggest-workflow | Ask the AI assistant to suggest a workflow from a natural-language description | | validate-workflow | Validate a workflow definition locally -- checks node types and required config fields (no auth, no API call) |

Available Resources

| URI | Description | |-----|-------------| | velaflows://services | Complete catalog of all VelaFlows API services with endpoint counts | | velaflows://nodes | Complete catalog of all workflow nodes grouped by category | | velaflows://events | Complete catalog of all platform events grouped by category | | velaflows://auth-guide | Authentication and authorization guide: tokens, headers, scopes, best practices | | velaflows://workflow-guide | Workflow automation guide: triggers, DAG execution, conditions, loops, error handling | | velaflows://services/{name} | Full API reference for a specific service with all endpoints (dynamic) | | velaflows://nodes/{type} | Full details for a specific workflow node including config fields and examples (dynamic) | | velaflows://events/{type} | Full details for a specific platform event including use cases (dynamic) |

Available Prompts

| Prompt | Description | |--------|-------------| | build-integration | Plan an API integration based on a description of what you want to build | | build-workflow | Design a workflow automation based on a description of what you want to automate | | debug-api-error | Diagnose a VelaFlows API error with status code, endpoint, and optional response body | | generate-code | Generate code to call VelaFlows APIs in JavaScript, Python, or cURL | | explain-event | Get a detailed explanation of a platform event: what triggers it, payload structure, and use cases | | migrate-webhook | Get guidance on migrating webhooks from another platform to VelaFlows events |

Architecture

mcp-server/
├── bin/cli.ts                  # npx entry point
├── src/
│   ├── index.ts                # Transport setup (stdio / SSE)
│   ├── server.ts               # McpServer assembly
│   ├── api/client.ts           # HTTP client for VelaFlows API
│   ├── auth/token.ts           # Token management
│   ├── data/loader.ts          # DataStore — loads bundled YAML/JSON
│   ├── tools/
│   │   ├── reference.ts        # 8 read-only reference tools
│   │   ├── api-proxy.ts        # 8 authenticated API proxy tools
│   │   └── workflow-builder.ts # 6 workflow builder tools
│   ├── resources/index.ts      # 8 MCP resources (5 static + 3 dynamic)
│   ├── prompts/index.ts        # 6 MCP prompts
│   └── types.ts                # Shared TypeScript types
├── data/
│   ├── openapi/                # 34 OpenAPI YAML specs
│   ├── nodes.json              # 464 workflow node definitions
│   └── events.json             # 392 platform event definitions
├── Dockerfile                  # Multi-stage Docker build for SSE deployment
└── package.json

Docker

Build and run the SSE server:

docker build -t velaflows-mcp .
docker run -p 3100:3100 velaflows-mcp

The container runs in SSE mode by default. Override environment variables as needed:

docker run -p 3100:3100 \
  -e PORT=3100 \
  velaflows-mcp

Health check endpoint: GET /health

License

MIT