Local Setup (CLI)

Run the MCP server on your machine using stdio transport. This is the fastest and most reliable option for development tools like Claude Code, Cursor, Windsurf, and VS Code.

Prerequisites

• Node.js 18+ installed (download )
• A VelaFlows API token (create one in your dashboard under Developer → API Tokens)
• Your Workspace ID (visible in the URL when you’re in your workspace)

Step 1: Install the MCP Server

Option A: Global Install (recommended)

npm install -g @velaflows/mcp-server

Verify it works:

velaflows-mcp-server
# Should print: VelaFlows MCP server started (stdio)
# Press Ctrl+C to stop

Option B: Use npx (no install)

You can also run it directly with npx — your AI tool will do this automatically if configured:

npx -y @velaflows/mcp-server

Step 2: Find Your Credentials

API Token

1. Go to your VelaFlows dashboard
2. Navigate to Developer → API Tokens
3. Click + Create Token
4. Give it a name (e.g., “MCP Server”)
5. Select the scopes you need (or select all for full access)
6. Click Create — copy the token immediately (it’s only shown once)

Your token looks like: sk_live_2Py5CTwo...

Workspace ID

1. Open your VelaFlows dashboard
2. Look at the URL — it contains your workspace ID
3. Or go to Settings → Workspace to find it

Step 3: Configure Your AI Tool

Claude Code

Add to your Claude Code MCP configuration file (~/.claude/settings.json or project-level .claude/settings.json):

{
  "mcpServers": {
    "velaflows": {
      "command": "velaflows-mcp-server",
      "env": {
        "VELAFLOWS_API_TOKEN": "sk_live_your_token_here",
        "VELAFLOWS_WORKSPACE_ID": "your_workspace_id_here"
      }
    }
  }
}

If you used npx instead of global install:

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

Cursor

Add to your Cursor MCP settings (Settings → MCP Servers → Add):

{
  "mcpServers": {
    "velaflows": {
      "command": "velaflows-mcp-server",
      "env": {
        "VELAFLOWS_API_TOKEN": "sk_live_your_token_here",
        "VELAFLOWS_WORKSPACE_ID": "your_workspace_id_here"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "velaflows": {
      "command": "velaflows-mcp-server",
      "env": {
        "VELAFLOWS_API_TOKEN": "sk_live_your_token_here",
        "VELAFLOWS_WORKSPACE_ID": "your_workspace_id_here"
      }
    }
  }
}

VS Code (with MCP extension)

Add to your VS Code settings or MCP extension config:

{
  "mcpServers": {
    "velaflows": {
      "command": "velaflows-mcp-server",
      "env": {
        "VELAFLOWS_API_TOKEN": "sk_live_your_token_here",
        "VELAFLOWS_WORKSPACE_ID": "your_workspace_id_here"
      }
    }
  }
}

Step 4: Verify It Works

After configuring, restart your AI tool and try these commands:

1. “List all VelaFlows services” — should invoke the list-services tool and return 34 services
2. “Search for endpoints related to conversations” — should invoke search-api and return matching endpoints
3. “What config does the send-message workflow node need?” — should invoke get-node-details
4. “List my workspaces” — should invoke list-workspaces (requires valid token)

Environment Variables

Troubleshooting

”command not found: velaflows-mcp-server”

The global npm bin directory isn’t in your PATH. Fix:

# Find where npm installs global packages
npm config get prefix
 
# Add the bin directory to your PATH
# On macOS/Linux: add to ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"
 
# On Windows: the installer usually handles this
# Try reopening your terminal

“Token required” errors

Reference tools (search, list) work without a token. But if you’re trying to use live API tools (list-workspaces, create-workflow, etc.), make sure:

1. VELAFLOWS_API_TOKEN is set in the env block of your MCP config
2. The token is valid and not revoked
3. The token has the required scopes for the operation

Server doesn’t start

# Check Node.js version (need 18+)
node --version
 
# Try running directly to see errors
VELAFLOWS_API_TOKEN=sk_live_... velaflows-mcp-server

Tools not showing up in your AI tool

1. Restart your AI tool completely (not just reload)
2. Check the MCP server logs in your tool’s output panel
3. Verify the config JSON is valid (no trailing commas, correct paths)