Vela MCP Server

MCP (Model Context Protocol) server that exposes Vela RemotePC endpoints as tools, so AI clients (Claude Desktop, Cline, Cursor, Gemini, etc.) can control remote systems.

Architecture

The server supports two transport modes that share the same 150+ tool definitions (tools.py):

1. STDIO (single-tenant, per-process)

Each process is bound to one agent via environment variables. Run multiple agents by defining multiple entries in mcp_settings.json, each with its own env block.

MCP client config (cline_mcp_settings.json or claude_desktop_config.json):

{
  "mcpServers": {
    "vela-home": {
      "command": "/path/to/.venv/bin/mcp",
      "args": ["run", "vela_mcp/tools.py:mcp"],
      "cwd": "/path/to/vela-mcp",
      "env": {
        "VELA_API_URL": "https://vela.mikesplore.tech",
        "VELA_TOKEN": "<relay_secret>",
        "AGENT_ID": "agt_123"
      }
    },
    "vela-work": {
      "command": "/path/to/.venv/bin/mcp",
      "args": ["run", "vela_mcp/tools.py:mcp"],
      "cwd": "/path/to/vela-mcp",
      "env": {
        "VELA_API_URL": "https://vela.mikesplore.tech",
        "VELA_TOKEN": "<relay_secret>",
        "AGENT_ID": "agt_456"
      }
    }
  }
}

2. HTTP (multi-tenant, shared server)

A single server instance handles any number of agents. No per-agent env vars needed. The caller provides agent_id and relay_secret in one of two ways:

Claude.ai connector (only accepts a URL — secret goes in the path):

https://mcp.mikesplore.tech/mcp/agt_123:<relay_secret>

Local clients (Cline/Claude Desktop — accept headers):

url:     https://mcp.mikesplore.tech/mcp/agt_123
headers: { "Authorization": "Bearer <relay_secret>" }

The server eagerly validates the credentials against the relay on session start, then forwards all tool calls through the relay — which enforces tenant isolation on every request.

How multi-tenancy works

• vela-mcp does not store agent credentials. It extracts agent_id from the URL path and relay_secret from the Authorization header on each incoming request.
• velavps (the relay server) enforces isolation: _verify_agent_access(agent_id, secret) rejects requests where the secret doesn't match the agent's registered secret, or where the agent belongs to another user.
• 150+ tools are untouched — they call vela_client.get/post/… which resolves to either the per-request or per-process client automatically.

Quick Start

python -m vela_mcp.server

Server starts on http://0.0.0.0:8002 with the MCP endpoint at /mcp/{agent_id}.

Setup

1. Copy .env.example to .env
2. Set VELA_API_URL — your Vela relay VPS host (e.g. https://vela.mikesplore.tech)
3. For stdio mode: also set VELA_TOKEN (relay secret) and AGENT_ID
4. For HTTP mode: you only need VELA_API_URL and PORT; credentials come from the client

Run Script

./run.sh            # start the MCP server (HTTP/streamable transport)
./run.sh dev        # start the MCP Inspector (dev/testing UI)

Project Layout

vela_mcp/
  __init__.py
  config.py      # Settings (VELA_API_URL, VELA_TOKEN, AGENT_ID, PORT)
  client.py      # RelayConnection, VelaClient, per-request contextvar proxy
  server.py      # FastAPI app with multi-tenant middleware at /mcp/{agent_id}
  tools.py       # 150+ MCP tool definitions (unchanged)

Development

.venv/bin/mcp dev vela_mcp/tools.py:mcp

Requirements

• Python >= 3.10
• mcp >= 1.0.0
• fastapi >= 0.110.0
• httpx >= 0.27.0
• pydantic-settings >= 2.0.0
• uvicorn >= 0.30.0