Skip to content

MCP Server

YData MCP server exposes the SDK's connectors, data profiling, metadata, and synthetic data generation capabilities as tools over the Model Context Protocol (MCP) — so any MCP-enabled AI client (Claude Desktop, Claude Code, Cursor, and others) can browse your data sources, profile datasets, and train and sample synthesizers directly from a conversation.

Instead of writing Python against the SDK, you describe what you want and the AI client drives the tools for you:

"Read the customers table from the warehouse connection, profile it, train a synthesizer on it, generate 10,000 synthetic rows, and compare the synthetic data against the original."

Each step in that sentence maps to a tool on this server — read_rdbms_table, profile_dataset, train_regular_synthesizer, sample_regular_synthesizer, compare_profiles — chained together by the client, with every intermediate artifact (cached files, trained models, reports) staying on the server's own filesystem.

Design principles

  • Credentials never flow through the conversation. Connections and LLM provider credentials are configured server-side in JSON files (YDATA_MCP_CONNECTIONS and YDATA_MCP_LLM_CONFIG); a tool call only ever carries a connection or provider name. The AI model in the loop never sees a hostname, port, bucket name, or key. See Installation & configuration.

  • Long work never blocks a tool call. MCP clients enforce their own tool-call timeout (Claude Desktop caps a call at roughly four minutes), and training a synthesizer or reading a large table routinely takes longer. Every heavy tool therefore starts its work as a background job and returns a job_id immediately; the client polls get_job_status(job_id) until the job completes. Failures surface through the same mechanism, with the full exception type, message, and traceback — so a failed training run is diagnosable from the conversation, without server-side log access.

  • Flexible data sources. Tools that consume a dataset accept it as a local file path, a file uploaded through the conversation itself (base64-encoded), or a table/query/file behind a configured connection — and profiling comparisons can mix those freely (for example, a live production table against an uploaded synthetic sample).

  • Files stay server-side, with an escape hatch. Generated samples, models, and reports are written to the server's filesystem and referenced by path between tools. When the client needs actual content back (for example, the server runs inside a container), download_file returns a file's content as base64.

What's available

Capability Tools
Connections list, health-check, browse, and inspect schemas for object storage (S3, GCS, Azure Blob, local), RDBMS (PostgreSQL, MySQL, Snowflake, Azure SQL), BigQuery, and Databricks (Lakehouse and Unity Catalog); read, write, and query with caching to local files
Dataset & metadata structural inspection (describe_dataset), full data-quality metadata as JSON (compute_dataset_metadata), file upload/download
Profiling full profiling reports (profile_dataset) and side-by-side dataset comparisons (compare_profiles) rendered as self-contained HTML
Synthetic data train/sample pairs for tabular, time-series, faker (spec-driven), and multi-table synthesizers; LLM-backed schema bootstrap and generation
Documents & Q&A LLM-backed synthetic document generation (from scratch, from configs, or from a template image/PDF) and Q&A pair extraction

See the full Tools & resources reference for every tool and its parameters.

Getting started

  1. Install and configure the server — one pip install, plus a JSON file naming your connections.
  2. Connect your MCP client — point Claude Desktop, Claude Code, or Cursor at the ydata-mcp-server command.
  3. Ask your client what it can do — "what tools does the ydata MCP server give you?" — and start working with your data.