Skip to main content

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.

Prerequisites​

Before you start, make sure that you have:

  • An MCP Server URL. For more information about how to find the MCP Server URL, see Connection Methods.
  • 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>

Step 1. Configure your AI client or gateway​

Choose one of the following clients or gateways. Replace the example URL and credentials with your MCP Server 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.

Step 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. If the response reports that VeloDB Cloud is connected, the client or gateway is ready to query the warehouse.

Step 3. Run your first query​

Start with metadata discovery.

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 sequentially calls list_databases, list_tables, describe_table, and execute_query. The execute_query tool accepts read-only SQL statements only (SELECT, SHOW, DESCRIBE, and EXPLAIN). DML, DDL, multiple statements, and SELECT INTO OUTFILE/DUMPFILE are blocked.

You have completed the quickstart when the AI agent returns metadata or rows from a table that your warehouse user can access.

Query examples​

After discovering your table structure, ask the AI agent to filter or aggregate the data. Replace the placeholders with a database and table that your warehouse user can access:

Show at most 10 rows from <database-name>.<table-name>.

For an orders table with status, amount, and order_date columns, you can ask:

Show the order count and total amount by status for the past week.

The AI agent uses the table metadata to generate a read-only SQL statement and calls execute_query.

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.

Can the AI agent perform writes?​

No. execute_query accepts read-only SQL only. DML, DDL, stacked statements, and SELECT INTO OUTFILE/DUMPFILE are blocked.

Queries are slow​

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

See also​

  • Overview explains the available tools and how the AI agent discovers metadata and runs read-only SQL queries.
On This Page