Get Started with the VeloDB MCP Service

Connect an AI agent to the VeloDB MCP Service, verify the connection, and complete your first read-only query. You do not need a semantic model to get started.

Prerequisites

Before you start, make sure you have:

• An MCP Connection URL. Log in to the VeloDB Cloud console, open your warehouse and click Connection to find the MCP Connection URL.
• The username and password of a warehouse user. To create or manage warehouse users, see Warehouse Users and Roles.
• A supported MCP client or gateway, such as Claude Code, Cursor, Visual Studio Code, Codex, and LiteLLM.
• Access to at least one database in the warehouse if you want to query your own data.

The client or gateway sends your warehouse username and password as a Bearer token in this format:

Authorization: Bearer <username>:<password>

1. Configure your AI client or gateway

Choose one of the following clients or gateways. Replace the example URL and credentials with your MCP Connection URL and warehouse credentials.

Claude Code

Run:

claude mcp add --transport http velodb https://<warehouse-id>.<region>.aws.velodb.cloud/mcp \
  --header "Authorization: Bearer <username>:<password>"

Restart Claude Code after adding the server.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "velodb": {
      "url": "https://<warehouse-id>.<region>.aws.velodb.cloud/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer <username>:<password>"
      }
    }
  }
}

Reload the Cursor window after saving the file.

Visual Studio Code

Create .vscode/mcp.json in your workspace root:

{
  "servers": {
    "velodb": {
      "type": "http",
      "url": "https://<warehouse-id>.<region>.aws.velodb.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <username>:<password>"
      }
    }
  }
}

Open the Command Palette, run MCP: List Servers, select velodb, and start the connection.

Codex

Add the server to ~/.codex/config.toml, or use .codex/config.toml in a trusted project:

[mcp_servers.velodb]
url = "https://<warehouse-id>.<region>.aws.velodb.cloud/mcp"
http_headers = { Authorization = "Bearer <username>:<password>" }

Restart the Codex client after saving the configuration. In the Codex terminal UI, use /mcp to view the connected server. The Codex CLI, IDE extension, and desktop app share the same MCP configuration.

LiteLLM

Use LiteLLM Proxy when you want to make VeloDB MCP tools available through a centralized AI gateway. Install LiteLLM Proxy before you start.

Add to litellm-config.yaml:

mcp_servers:
  velodb:
    transport: http
    url: https://<warehouse-id>.<region>.aws.velodb.cloud/mcp
    auth_type: bearer_token
    auth_value: "<username>:<password>"
    static_headers:
      Accept: application/json, text/event-stream

Restart LiteLLM Proxy after saving the configuration.

After the proxy starts, follow LiteLLM Model Management to add a tool-calling model through /model/new. Provide the model name, provider model, and provider credentials. Database storage must be enabled for the model to persist across restarts.

2. Verify the connection

Ask the AI agent:

Check service health.

The AI agent calls check_service_health and returns the VeloDB Cloud connection status and the state of each semantic workspace. If the response reports that VeloDB Cloud is connected, the client or gateway is ready to query the warehouse.

The workspace state does not determine whether the MCP connection succeeded:

Workspace state	Meaning	What to do next
healthy	A semantic model is loaded and its metrics are available.	Query metrics or use metadata and read-only SQL.
no_models	No semantic model has been published. This is a valid initial state.	Continue with metadata and read-only SQL.
not_ready	Model files exist but could not be loaded.	Continue with metadata and SQL, and ask an administrator to fix the model.

3. Run your first query

Start with metadata discovery. This path does not require a semantic model.

Ask:

List the databases I can access.

Choose a database from the result, then ask:

List the tables in <database-name>.

Choose a table and run your first read-only data query:

Describe <database-name>.<table-name>, then show at most 10 rows from it.

The AI agent calls list_databases, list_tables, describe_table, and execute_query. The execute_query tool accepts SELECT, SHOW, DESCRIBE, and EXPLAIN statements only.

You have completed the quickstart when the AI agent returns metadata or rows from a table that your warehouse user can access. A no_models state does not prevent this query path.

4. Optional: deploy the example with Semantic Web UI

If you want to try the semantic query path, a warehouse administrator can deploy the bundled example. This step is optional and does not affect your ability to query existing warehouse data with read-only SQL.

Semantic Web UI is the web interface for viewing semantic workspaces and models. Warehouse administrators also use it to manage workspaces, edit and publish models, and deploy the bundled example.

To open Semantic Web UI and deploy the example:

1. Open Semantic Web UI by appending /web to the MCP Connection URL. For example, open https://<warehouse-id>.<region>.aws.velodb.cloud/mcp/web.
2. Log in with the warehouse admin username and password.
3. Click Deploy example.
4. Wait for the background deployment to finish. The page checks the deployment status and redirects when it completes.
5. Return to the AI agent and ask it to check service health again.

The deployment creates:

• The dw.orders, dw.users, dw.products, and dw.dim_date sample tables.
• The example semantic workspace.
• The orders.yaml, users.yaml, products.yaml, and project.yaml model files.
• Metrics such as total_amount, order_count, avg_amount, unique_users, and user_count.

After the example workspace reports healthy, ask:

List all metrics in the example workspace.

Then run a semantic query:

Show the total order amount by channel for the past 7 days.

The AI agent calls list_metrics to find the metric, list_dimensions_for_metric to find grouping fields, and then query_metric to run the semantic query.

Query examples

The following examples use the sample data and semantic models installed by Deploy example.

Explore the data structure

You: List all databases
AI: [calls list_databases]
    dw

You: What tables are in the dw database?
AI: [calls list_tables]
    orders, users, products, dim_date

You: Show the structure of the orders table
AI: [calls describe_table]
    Column      Type      Comment
    order_id    BIGINT    Order ID
    user_id     BIGINT    User ID
    amount      DECIMAL   Amount
    channel     VARCHAR   Channel
    status      VARCHAR   Status
    order_date  DATE      Order date

Query data with read-only SQL

You: Show the order count and total amount by status for the past week
AI: [calls execute_query]
    status      count   total_amount
    completed   1234    567890.00
    pending     567     89012.00
    cancelled   89      12345.00

Query semantic metrics

You: List all available metrics
AI: [calls list_metrics]
    total_amount      Total order amount
    order_count       Order count
    avg_amount        Average order value
    unique_users      Distinct ordering users
    user_count        User count

You: Show total order amount by channel for the past 7 days
AI: [calls list_dimensions_for_metric] -> channel
    [calls query_metric]
    channel   total_amount
    Online    12345.00
    Offline   15678.00
    ...

Semantic query conversation

User: What was the total order amount by channel in April 2026?

AI reasoning:
  1. get_query_guide -> got the guide
  2. check_service_health -> workspace "example" healthy, 5 metrics
  3. Involves "total amount" and "channel" -> use the semantic layer
  4. list_metrics(example) -> total_amount
  5. list_dimensions_for_metric(example, total_amount) -> channel
  6. query_metric(example, metrics=[total_amount], group_by=[channel],
                  where="order_date >= '2026-04-01' AND order_date < '2026-05-01'")

AI reply:
  channel  total_amount
  WEB      1,096.00
  APP      2,396.00
  MINI       298.00

Troubleshooting

The connection fails with a 401 response

Make sure the Authorization header contains your warehouse username and password, joined by an ASCII colon in the format username:password.

The health check reports no_models

The connection succeeded, but no semantic model is available. You can query warehouse metadata and run read-only SQL. Ask a warehouse administrator to publish a model or deploy the bundled example if you need to try semantic metrics.

A semantic query returns workspace not found

Make sure the workspace name is correct. The example workspace exists only after a warehouse administrator deploys the bundled example. Log in to Semantic Web UI to see the available workspaces.

Can the AI agent perform writes?

No. execute_query allows SELECT, SHOW, DESCRIBE, and EXPLAIN statements only.

Queries are slow

For large data volumes, ask the AI agent to add a LIMIT or narrow the time range.

Which metrics can the semantic layer use?

Ask the AI agent to list all metrics, or log in to Semantic Web UI to view the metrics configured for each workspace.

See also

• Overview explains the available tools and how the AI agent chooses between semantic queries and read-only SQL.
• Semantic model concepts explains entities, dimensions, measures, and metric definitions.
• Create and manage semantic models explains how to create, validate, commit, and publish governed business metrics.