Tools & resources

The server's tools, resources and prompts, 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, read_schema_document, test_connection, faker_config_from_llm_schema) never move real data and stay fully synchronous.

Arguments are validated before any job starts: an invalid source or an invalid calculated_features entry fails the tool call itself. train_faker_synthesizer validates its whole configuration inline — an invalid one returns, without a job:

{ "status": "invalid",
  "errors": ["Table 'customers': Date min/max not defined for column signup_date."],
  "gaps": { "customers": { "signup_date": ["min", "max", "format"] },
            "order_items": { "unit_price": ["min", "max"] } } }

errors names the field paths; gaps lists every option still missing across all tables, so the client can fix the configuration in one round and call again.

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, SAP HANA

Tool	Async	Description
`browse_rdbms(connection, schema_name=None, tables=None)`		Tables and their column names for a schema. `tables` limits it to a subset — required for SAP S/4HANA, whose ABAP schema is too large to list whole.
`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.
`read_schema_document(...)`		Read a schema described in a document — a data dictionary saved as CSV (export an Excel sheet as CSV first): every row as text, up to `max_rows`, with `n_rows` and `truncated`. Nothing is assumed about the layout; the client interprets it. 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(config, ...)`	✔	Configure a synthesizer from a declarative configuration — no input dataset. The same configuration as the FakerSynthesizer YAML, inline (`config`) or as a file on the server (`config_path`): a single table (`columns` plus scaffold, distributions, conditions, sequence, totals, derived tables, errors, time behaviour) or a database (`tables` with primary/foreign keys and cardinalities). `reference_data`/`existing_data` take files or uploads. Validated inline (see Background jobs). `columns` (a bare column mapping) is deprecated.
`sample_faker_synthesizer(model_path, sample_size, ...)`	✔	Generate from the configuration. `sample_size` per root table (`{table: rows}`), `random_state` for reproducibility. Several tables (a database, or derived tables) are written as one CSV per table under `output_dir`; injected errors come back as `error_labels_path`, one row per error.
`faker_config_from_llm_schema(tables)`		For the Faker use case when the user has only the idea of the schema: convert an LLM schema (`generate_llm_schema`'s result) into a Faker configuration skeleton plus `gaps` — `{table: {column: [missing options]}}`, e.g. `{"customers": {"age": ["min", "max"]}}`.
`train_multitable_synthesizer(...)`	✔	Fit across a whole relational schema at once, preserving foreign keys — from a live RDBMS `connection` (optionally limited to `connection_tables`, required for SAP S/4HANA), 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 — for `generate_llm_synthetic_data`, or as the starting point of a Faker configuration.
`generate_llm_synthetic_data(tables, provider, ...)`	✔	Fit-and-sample an LLM synthesizer on a schema in one call.

Calculated features

Calculated features are business rules — gross = net + tax, line amounts, running balances, aggregations — computed deterministically from other columns. They are part of the synthesizer's configuration: every train tool (and generate_llm_synthetic_data) takes a calculated_features argument, and the synthesizer applies them so the sample already satisfies them. They are never applied to a sampled file as a separate step.

Over MCP, function names a pre-defined rule, with constants fixed through params:

[{ "calculated_features": "gross_value", "function": "gross_up",
   "params": { "rate": 0.23 }, "calculated_from": ["net_value"] }]

Single-table synthesizers name columns bare; multi-table ones use table.column, with reference_keys for inputs from another table. Rules written in Python (relations outside the catalog) are used with the SDK directly — the server does not run code sent by the client.

Tool	Async	Description
`list_calculated_features()`		The catalog of pre-defined rules: name, signature (the input order for `calculated_from`), whether it is windowed (computed per entity in time order), and description.

Prompts

Reusable workflows the user picks from the client's prompt menu.

Prompt Description

identify_calculated_features(source) Find the calculated features in a dataset or schema — a connection, a data file, a data dictionary (CSV), a Faker or LLM configuration, or a schema pasted in the conversation. The client reads the schema only (no data scan; a schema alone is enough), matches catalog rules on column names and descriptions, writes vectorised Python for relations the catalog does not cover (aggregations included), and presents the proposals for review before any of them reaches a train call. Independent of the synthesizer.

The proposals come back in this shape:

{ "proposals": [{ "table": "order_items",
                  "feature": { "calculated_features": "line_amount", "function": "line_amount",
                               "calculated_from": ["quantity", "unit_price", "discount"] },
                  "rationale": "...", "evidence": "names+descriptions",
                  "requires": {}, "open_questions": [] }],
  "not_in_catalog": [{ "table": "orders", "relation": "order total = sum of the order's line amounts",
                       "calculated_features": "orders.order_total",
                       "calculated_from": ["order_items.gross_amount"],
                       "reference_keys": { "source": "order_items.order_id", "target": "orders.order_id" },
                       "python": "def order_total(gross_amount, order_id): ...",
                       "open_questions": [] }] }

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.