<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->

VeloDB MCP Server

VeloDB MCP Server is a backend service that exposes VeloDB through the Model Context Protocol (MCP). AI clients (Claude Desktop, Cursor, VS Code, and others) can query VeloDB data through a governed semantic metrics layer built on MetricFlow, with raw-SQL discovery as a fallback path. It ships with a Web UI for managing semantic models and a CLI client for scripting.

Core Features

• Semantic Metrics Layer: Define metrics once in YAML (simple / ratio / derived / cumulative / conversion), query them from any MCP client. MetricFlow compiles semantically correct SQL — no hand-written aggregation queries.
• Multi-Workspace Isolation: Fully isolated tenants with their own models, compiler, and VeloDB storage tables. Models are stored in VeloDB itself (active + staging tables), so multiple server nodes share state without file sync.
• Staging Workflow: All model changes go through staging → validate → commit; broken models can never affect running queries.
• Guided Tooling: 10 MCP tools with an enforced workflow (get_query_guide → check_service_health → semantic query, or metadata discovery → raw SQL fallback).
• Credential Pass-Through: Authorization: Bearer <velodb-user>:<password> — every query runs under the caller's own VeloDB identity with per-user connection pools. No shared admin credentials.
• Web UI: Login with VeloDB credentials to edit/validate/publish models, manage workspaces, and deploy the bundled example — no YAML tooling required.
• CLI Client: mcp-client for calling tools and pushing/pulling model files from scripts and CI/CD.
• Multi-Node Ready: Session affinity is handled in-app using the server IP recorded in the Web UI cookie; nginx stays a plain reverse proxy.
• Self-Contained Packaging: Release tarballs bundle a Python 3.10 runtime and all dependencies. No network, no pip, no system Python required on target machines.

System Requirements

• Server host: Linux x86_64 or ARM64 (for running the release package)
• Database: any MySQL-protocol-compatible Doris-family cluster — VeloDB Cloud, VeloDB Enterprise, or Apache Doris — with the FE reachable (default 127.0.0.1:9030)
• Building from source: curl/wget, or a local Python 3.10.x for offline builds

🤖 Install with an AI Agent (no docs reading required)

If you use Claude Code (or another MCP-capable agent), you don't need to read this README at all. Just paste this into your agent:

"Install this MCP server per this README and tell me how to connect my VeloDB cluster."

The agent will:

1. Ask you 2 questions — your VeloDB connection address and credentials (works the same for VeloDB Cloud, VeloDB Enterprise, and Apache Doris, all of which speak the MySQL protocol), and where to install.
2. Download the matching release (self-contained: Python runtime and all dependencies are bundled — nothing else to install).
3. Configure mcp-server.toml, start the server, and health-check it.
4. Register itself as the velodb MCP server in your AI client.
5. Verify the connection end-to-end and confirm you can start querying.

The agent-facing step-by-step playbook (including failure handling) lives in AGENTS.md. Agents reading this README should follow that file.

🚀 Quick Start

1. Get the package

Download the latest release from Releases:

tar xzf velodb-mcp-server-<version>-linux_x64.tar.gz
cd velodb-mcp-server

Or build from source (see Building from Source).

2. Start the server

The default points to a same-host VeloDB FE (127.0.0.1:9030). For a separate deployment, set server.fe_host to the FE private IP or hostname, then:

# Foreground
./start-mcp-server.sh

# Background
nohup ./start-mcp-server.sh > /dev/null 2>&1 &

The server listens on port 3000 by default.

3. Connect your MCP client

Authentication is your VeloDB username and password passed as a Bearer token:

Authorization: Bearer <velodb-user>:<velodb-password>

Claude Desktop / Claude Code:

claude mcp add --transport http velodb http://<host>:3000/mcp \
  --header "Authorization: Bearer <user>:<password>"

Cursor / VS Code (mcp.json):

{
  "mcpServers": {
    "velodb": {
      "type": "http",
      "url": "http://<host>:3000/mcp",
      "headers": {
        "Authorization": "Bearer <user>:<password>"
      }
    }
  }
}

A ready-to-copy template is provided at mcp.json.example.

Smoke-test the connection with the FastMCP CLI:

fastmcp call http://<host>:3000/mcp check_service_health \
  --auth "<user>:<password>" --json

4. Deploy the example workspace (Web UI)

1. Open http://<host>:3000/mcp/web and log in with your VeloDB credentials (management operations require the VeloDB admin user).
2. Click the example deploy button. Deployment runs in the background; the page polls progress and redirects when done.
3. Back in your AI client, ask: "What is the total order amount by channel?" — the agent will discover the example workspace and query metrics like total_amount grouped by channel.

5. Manage semantic models

Web UI (/mcp/web): create/upload/edit YAML models → Validate → Commit. Only validated models go live.

CLI client:

export VELODB_MCP_SERVER=http://<host>:3000
export VELODB_MCP_TOKEN=<user>:<password>

./mcp-client.sh semantic push ./models -w my_workspace
./mcp-client.sh semantic pull -o ./backup -w my_workspace
./mcp-client.sh tool call list_metrics --json '{"workspace":"my_workspace"}'

How the Agent Queries Data

get_query_guide()              ← 1. workflow instructions (always first)
check_service_health()         ← 2. VeloDB connectivity + workspace status
    │
    ├─ semantic layer healthy ─→ list_metrics → list_dimensions_for_metric → query_metric
    │                             (counts, sums, ratios, rankings, trends)
    └─ no matching metric ─────→ list_databases → list_tables → describe_table → execute_query
                                  (raw SQL fallback, read-only validated)

Configuration (mcp-server.toml)

Key	Default	Description
server.mcp_host / server.mcp_port	0.0.0.0 / 3000	HTTP listen address
server.fe_host / server.fe_port	127.0.0.1 / 9030	VeloDB FE endpoint; set a private IP or hostname for remote FE deployment
query.db_whitelist	[]	Optional database allow-list
query.query_timeout_seconds	600	SQL query timeout
query.query_max_rows	10000	Max rows per query

All values support ${ENV_VAR} interpolation.

Multi-Node Deployment

Multiple server nodes behind one load balancer work without an affinity configuration. On the first successful Web UI login, a concrete server.mcp_host is written directly into the session cookie; when listening on 0.0.0.0, the server instead reads the local IPv4 address on which the request arrived. The cookie format is session_id.<server-ip>. If a later request reaches another node, the middleware forwards it to the node recorded in the cookie. nginx needs no cookie parsing, and /mcp traffic stays node-local. See DESIGN.md §8.3 for details.

Building from Source

./build.sh linux-x64      # Linux x86_64
./build.sh linux-arm64    # Linux ARM64
./build.sh macos-arm64    # macOS Apple Silicon
./build.sh clean          # remove build artifacts

The build downloads a standalone Python 3.10 and produces a self-contained tarball in dist/. If GitHub is unreachable, point to a local Python 3.10:

VELODB_MCP_SYSTEM_PYTHON=/opt/miniconda3/bin/python ./build.sh linux-x64

CI releases (.github/workflows/release.yml): pushing a tag named velodb-mcp-server-x.y.z builds linux-x64 + linux-arm64 packages and publishes a GitHub Release for that version. A release can also be triggered manually from the Actions page.

Running Tests

bash test/run_all_tests.sh --offline   # unit tests, no server needed
bash test/run_all_tests.sh --smoke     # quick smoke test
bash test/run_all_tests.sh             # full suite (needs a local server)

Documentation

• AGENTS.md — agent-facing installation playbook (AI agents read this to install everything automatically)
• DESIGN.md — architecture and design decisions
• INSTALL.html — installation guide
• velodb-mcp-docs.html — semantic model reference and user guide

License

Licensed under the Apache License, Version 2.0. This distribution vendors MetricFlow (src/metricflow/), which carries its own license — see src/metricflow/LICENSE and src/metricflow/NOTICE.