Tools & resources

The server exposes 42 tools and 4 resources, grouped below by capability. Tools marked async run as background jobs: they return a job_id immediately, and the result is fetched with get_job_status.

Background jobs

MCP clients enforce their own tool-call timeout (Claude Desktop caps a call at roughly four minutes), while reading a large table, training a synthesizer, or profiling a real dataset routinely takes longer. Every such tool therefore starts its work on a background thread and returns immediately:

{ "job_id": "63afa8cd1fc54285be20f281617ecf65", "status": "running" }

The client polls get_job_status(job_id) every few seconds. status is "running", "completed", or "failed":

completed — result holds what the tool would otherwise have returned directly (e.g. local_path/shape/columns for a read, model_path for training, report_path for profiling).
failed — error holds "<ExceptionType>: <message>" and traceback the full Python traceback from inside the job, so a failure is diagnosable from the conversation without server-side log access.

Cheap metadata lookups (browse_*, list_*, get_*_table_schema, describe_dataset, test_connection) never move real data and stay fully synchronous.

Tool	Description
`get_job_status(job_id)`	Status/result of any background job started by any tool below.

Dataset sources

Tools that consume a dataset — profile_dataset, compare_profiles, compute_dataset_metadata, train_regular_synthesizer, train_timeseries_synthesizer — accept it as exactly one of three sources:

Source	Parameters	Notes
Local file	`input_path`	CSV or parquet already on the server's filesystem (e.g. written by a connector `read_*` tool).
Upload	`content_base64` + `filename`	A file uploaded through the conversation itself. Practical for small files only — base64 inflates ~33% and flows through the model's context.
Connection	`connection` + a per-family selector	Read inside the background job. Selectors: `table` or `query` (RDBMS), `query` (BigQuery), `file` (object storage), `table` + `warehouse`, optionally `catalog`/`schema_name` (Databricks Lakehouse).

compare_profiles takes a list of such source specs and mixes them freely — for example a live production table against an uploaded synthetic sample.

Connections

Configured via YDATA_MCP_CONNECTIONS — see Installation & configuration. Tools reference connections by name only.

Any connection

Tool	Async	Description
`list_connections()`		Names and types of every configured connection — never credentials.
`test_connection(connection)`		Health-check: `{"ok": true}` or `{"ok": false, "error": ...}`.

Object storage — S3, GCS, Azure Blob, local filesystem

Tool	Async	Description
`browse_object_storage(connection, path=None)`		List buckets/containers, or a location's contents.
`read_object_storage_file(connection, path, ...)`	✔	Read a file, caching it to a local path other tools can use.
`write_object_storage_file(connection, local_path, destination)`	✔	Write a local file out to the storage.

RDBMS — PostgreSQL, MySQL, Snowflake, Azure SQL

Tool	Async	Description
`browse_rdbms(connection, schema_name=None)`		Tables and their column names for a schema.
`list_rdbms_schemas(connection)`		Schema names available on the connection.
`get_rdbms_table_schema(connection, table, schema_name=None)`		Full column metadata: types, nullability, primary/foreign keys.
`read_rdbms_table(connection, table, ...)`	✔	Read a table (optionally sampled) to a local file.
`write_rdbms_table(connection, local_path, table, ...)`	✔	Write a local file into a table.
`query_rdbms(connection, query, ...)`	✔	Run SQL and cache the result locally.

BigQuery

Tool	Async	Description
`browse_bigquery(connection, dataset=None)`		List datasets, or a dataset's tables.
`get_bigquery_table_schema(connection, dataset, table)`		BigQuery's native field schema for one table.
`query_bigquery(connection, query, ...)`	✔	Run SQL and cache the result locally (BigQuery reads are query-driven).

Databricks — Lakehouse & Unity Catalog

Tool	Async	Description
`list_databricks_warehouses(connection)`		SQL warehouses available to a Lakehouse connection.
`browse_databricks_lakehouse(connection, ...)`		Catalogs → schemas → tables.
`read_databricks_lakehouse_table(connection, table, warehouse, ...)`	✔	Read a Unity Catalog table via a SQL warehouse.
`write_databricks_lakehouse_table(connection, local_path, table, warehouse, ...)`	✔	Write a local file into a Unity Catalog table.
`query_databricks_lakehouse(connection, query, warehouse, ...)`	✔	Run SQL against a warehouse and cache the result.
`browse_databricks_unity_catalog(connection, ...)`		Shares → schemas → tables (Delta Sharing).
`read_databricks_unity_catalog_table(connection, ...)`	✔	Read a table shared with you via Delta Sharing.

Resources

Read-only views a client can fetch without a tool call:

Resource URI	Description
`connection://list`	Same as `list_connections`.
`connection://{name}/catalog`	The connection's top-level catalog (buckets, tables, datasets, catalogs, or shares — by connection type).
`connection://{name}/schemas`	Schema names (RDBMS) or datasets (BigQuery).
`connection://{name}/schema/{table}`	Column metadata for one table (RDBMS, default schema).

Dataset & metadata

Tool	Async	Description
`describe_dataset(...)`		Cheap structural summary: shape, columns, inferred types, missing counts, preview. Local file or upload.
`compute_dataset_metadata(...)`	✔	The full data-quality picture as JSON: per-column statistics, correlation matrix, warnings, possible target columns. Any dataset source.
`save_uploaded_file(content_base64, filename)`		Decode an uploaded file to a local path, for feeding into any tool's `input_path`/`local_path`.
`download_file(path, max_bytes=2_000_000)`		Return a server-side file's content as base64 — how reports, samples, and models get back to the client when the server runs in a container. Raises above `max_bytes` rather than ballooning a response.

Profiling

Tool	Async	Description
`profile_dataset(...)`	✔	Full profiling report (ProfileReport) written as self-contained HTML (or JSON), plus a reusable saved report (`.pkl`) and an inline summary with data-quality alerts. Any dataset source. Options: `minimal`, `explorative`, `sensitive`, `tsmode`+`sortby`, `outlier`, `title`.
`compare_profiles(inputs, ...)`	✔	Side-by-side comparison report across two or more sources, mixed freely — dataset files, uploads, connections, or `.pkl` reports saved by `profile_dataset` (loaded, not recomputed). The natural check after synthesis: original vs synthetic.

Synthetic data

Training and sampling are separate tools — one trained model can be sampled repeatedly with different options, without retraining.

Tool	Async	Description
`train_regular_synthesizer(...)`	✔	Fit a tabular synthesizer on any dataset source. Options: `condition_on`, `privacy_level`. Returns `model_path`.
`sample_regular_synthesizer(model_path, n_samples, ...)`	✔	Draw synthetic rows; supports conditional sampling (`condition_on`) and `balancing`.
`train_timeseries_synthesizer(sortby, ...)`	✔	Fit a time-series synthesizer (`sortby` orders time; `entities` separates series). Any dataset source.
`sample_timeseries_synthesizer(model_path, n_entities, ...)`	✔	Generate synthetic time series; `smoothing` and `fidelity` control noise vs diversity.
`train_faker_synthesizer(columns, ...)`	✔	Configure a synthesizer purely from a column spec — no input dataset (names, types, Faker hints like `"email"`, ranges/categories).
`sample_faker_synthesizer(model_path, sample_size, ...)`	✔	Generate fake-but-realistic rows from the configured spec.
`train_multitable_synthesizer(...)`	✔	Fit across a whole relational schema at once, preserving foreign keys — from a live RDBMS `connection`, or from per-table files (`tables` + an explicit `schema` of primary/foreign keys). The heaviest tool on the server.
`sample_multitable_synthesizer(model_path, n_samples, ...)`	✔	Generate all tables with referential integrity intact; write to local CSVs or stream straight into another RDBMS connection (`write_connection`).
`generate_llm_schema(description, provider, ...)`	✔	Bootstrap a table schema from a plain-English description, via an LLM.
`generate_llm_synthetic_data(tables, provider, ...)`	✔	Fit-and-sample an LLM synthesizer on a schema in one call.

Documents & Q&A (LLM-backed)

All of these require a provider argument naming a profile from YDATA_MCP_LLM_CONFIG — see Installation & configuration.

Tool	Async	Description
`generate_document(document_type, provider, ...)`	✔	Generate a synthetic document (invoice, contract, report, ...) from high-level attributes.
`generate_document_dataset(config, provider, ...)`	✔	Bulk document generation driven by a `DatasetConfig`-shaped JSON config.
`generate_document_from_template(document_type, information, template_img_path, provider, ...)`	✔	Generate documents matching a template image — PDFs are converted to images transparently.
`generate_qa_pairs(input_source, provider, ...)`	✔	Extract question/answer pairs from existing documents, for fine-tuning or RAG evaluation.