Overview

The MCP (Model Context Protocol) server for YDB provides a lightweight service that lets developers run SQL queries against YDB databases through a stable, secure HTTP API. It is intended for use cases where you need to execute fast analytics queries, fetch results for downstream processing (for example, ML feature generation), or expose curated datasets to applications without embedding YDB drivers into every consumer.

By centralizing query execution and dataset management, the MCP server simplifies access control, result paging, caching, and observability. It acts as a controlled gateway between clients and one or more YDB clusters, making it easier to manage credentials, rate limits, and dataset lifecycle while providing predictable performance for interactive and programmatic consumers.

GitHub: https://github.com/ydb-platform/ydb-mcp

Features

Run SQL queries against YDB over a simple HTTP/JSON API
Parameterized queries with typed parameters
Result streaming and pagination for large result sets
Dataset registration and name-based access control
Authentication and RBAC integration (token or mTLS)
Optional result caching for repeated analytical queries
Export results to CSV/Parquet for downstream ML pipelines
Prometheus metrics and structured logging for monitoring
Configurable timeouts, concurrency limits, and rate limiting

Installation / Configuration

You can run the MCP server as a container or build from source. Below are example install and configuration patterns.

Run with Docker (example):

docker run --rm \
  -e MCP_YDB_ENDPOINT="grpcs://ydb.example:2135" \
  -e MCP_SERVICE_TOKEN="s3cr3t-token" \
  -p 8080:8080 \
  ydb-platform/ydb-mcp:latest

Docker Compose example:

version: "3.8"
services:
  mcp:
    image: ydb-platform/ydb-mcp:latest
    ports:
      - "8080:8080"
    environment:
      - MCP_YDB_ENDPOINT=grpcs://ydb.example:2135
      - MCP_AUTH_MODE=token
      - MCP_SERVICE_TOKEN=s3cr3t-token
    restart: unless-stopped

Minimal configuration file (YAML):

ydb:
  endpoint: "grpcs://ydb.example:2135"
  database: "/ru/home/your-db"
auth:
  mode: "token"        # token | mtls
  token: "s3cr3t-token"
server:
  listen: ":8080"
  max_concurrency: 50
  query_timeout_seconds: 30
cache:
  enabled: true
  ttl_seconds: 300
metrics:
  prometheus: true

Configuration keys (summary):

Key	Description
ydb.endpoint	YDB endpoint (gRPC URL)
ydb.database	Default YDB database path
auth.mode	Authentication mode: token or mtls
auth.token	Static service token for simple auth
server.listen	HTTP listen address
server.max_concurrency	Max concurrent queries
cache.enabled	Enable query result cache
cache.ttl_seconds	Cache TTL for results

Build from source (example using Go):

git clone https://github.com/ydb-platform/ydb-mcp.git
cd ydb-mcp
make build
./bin/mcp-server --config ./config.yaml

Available Tools and Resources

GitHub repository: https://github.com/ydb-platform/ydb-mcp — source, issues, and releases
HTTP API (JSON) — endpoint examples below
CLI helper (optional) — small client to run queries from terminal (check repo tools/)
Prometheus metrics endpoint at /metrics
Example Postman collection in repo for quick testing
Documentation and config examples in the repository README and /docs

Example API Usage

Run a parameterized query (example HTTP request):

curl -s -X POST "http://localhost:8080/v1/query" \
  -H "Authorization: Bearer s3cr3t-token" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT user_id, count(*) AS cnt FROM events WHERE event_date >= $1 GROUP BY user_id",
    "params": { "1": "2026-01-01" },
    "page_size": 1000
  }'

Typical response (truncated):

{
  "query_id": "abc123",
  "columns": ["user_id", "cnt"],
  "rows": [
    ["u1", 42],
    ["u2", 27]
  ],
  "next_page_token": "def456"
}

Export results to CSV:

curl -s -X POST "http://localhost:8080/v1/query?format=csv" \
  -H "Authorization: Bearer s3cr3t-token" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM metrics LIMIT 10000"}' > metrics.csv

Use Cases

Interactive analytics dashboard: Front-end apps can request pre-defined dataset queries via the MCP API, relying on server-side caching and pagination to serve results quickly without exposing raw DB credentials.
ML dataset preparation: Data scientists can export curated feature tables as Parquet or CSV by invoking the MCP server, which runs optimized SQL and streams results directly to storage or the client.
ETL orchestration: Use MCP as a controlled query runner within pipelines—scheduling jobs that run heavy aggregations, export snapshots, and enforce query timeouts and concurrency limits.
Multi-tenant access control: Register logical datasets and use the MCP server to enforce which tenants can query which datasets, combined with token or mTLS authentication.
Metric collection and alerting: Periodic queries to detect anomalies can be scheduled through MCP, with the server emitting Prometheus metrics for observability.

For more details, sample configs and client examples, see the repository: https://github.com/ydb-platform/ydb-mcp.

Query YDB Databases on MCP Server