> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/soda-ai/soda-mcp/mcp-tools.md).
# MCP tools
The soda-mcp server exposes Soda Cloud's user-callable Public API v4 surface as Model Context Protocol tools, **letting your agent** **manage your data quality**, from datasets and contracts to secrets and runners, directly. The catalog below is grouped by resource type and generated from the server's tool definitions, so it stays in sync with what the server actually offers.
Each tool maps to a documented operation within Soda v4, with MCP-specific transformations and exclusions noted where they apply.
Attributes — labels for organizing datasets, checks, and columns
Attributes are labels scoped to a resource type (dataset, check, or column) that you use to categorize and organize resources (e.g. marking checks as critical to drive notification rules).
* `list_attributes` — List attribute definitions available in your Soda Cloud organization for datasets, checks, and columns.
* `create_attribute` — Create a new attribute definition for datasets, checks, or columns.
* `update_attribute` — Update an attribute's label, description, or allowed values.
* `delete_attribute` — Delete an attribute definition. The attribute is removed from any resources where it is set.
Checks — deterministic data quality validations
Checks are deterministic data quality validations defined in data contracts, with fixed thresholds that must be met to pass. Each scan analyzes the entire dataset unless a filter is defined in the contract.
* `list_checks` — List checks in your Soda Cloud organization, including associated datasets, agreements, and linked incidents.
* `delete_check` — Delete a specific check by its ID. Checks are deterministic validations defined in data contracts (not monitors).
Datasets — tables tracked in Soda Cloud
* `list_datasets` — List datasets in your Soda Cloud organization, including data source, incidents, attributes, and health status.
* `get_dataset` — Get a single dataset by dataset ID.
* `get_dataset_by_dataset_qualified_name` — Get a single dataset by dataset qualified name (DQN): \[datasource\_name]/\[database\_name]/\[schema\_name]/\[dataset\_name].
* `update_dataset` — Update dataset properties (label, tags, attributes, owners, profiling, metric monitoring, diagnostics warehouse, compute warehouse, time partition).
* `list_dataset_columns` — List active columns of a dataset with current assigned column attribute values.
* `set_column_attributes` — Set attribute values on columns of a dataset.
* `delete_dataset` — Delete a dataset. This action is permanent and cannot be undone.
* `list_dataset_roles` — List available dataset roles. Use dataset roles to manage access to individual datasets.
* `create_dataset_role` — Create a custom dataset role.
* `update_dataset_role` — Update the name or permissions of a custom dataset role.
* `delete_dataset_role` — Delete a custom dataset role. This action is permanent and cannot be undone.
* `get_dataset_compute_warehouse` — Get the compute warehouse configuration for a dataset.
* `get_dataset_diagnostics_warehouse` — Get diagnostics warehouse information for a dataset.
* `get_dataset_profiling` — Get profiling information for a dataset (structure, statistical summaries, data characteristics).
* `list_dataset_responsibilities` — List user and user group permissions assigned to a dataset, and their associated roles.
* `update_dataset_responsibilities` — Update user/group permissions and their associated roles for a dataset.
Monitors — ML-based dynamic-threshold metrics
Monitors track metrics over time using ML-based dynamic thresholds (anomaly detection). Each scan analyzes only the most recent time partition. There are three types:
1. **Dataset-level** — 6 fixed monitors (e.g. row count, freshness) that can be enabled/disabled
2. **Column monitors** — User-defined, track a built-in metric for a specific column
3. **Custom SQL monitors** — User-defined, track the result of a SQL query
* `get_dataset_metric_monitoring` — Get metric monitoring configuration for a dataset, including all three monitor types and the dataset-level scan schedule.
* `create_column_metric_monitor` — Create a user-defined column metric monitor for a dataset.
* `update_column_metric_monitor` — Update an existing user-defined column metric monitor (e.g. sensitivity, thresholds, grouping, exclusion zones).
* `delete_column_metric_monitor` — Delete a user-defined column metric monitor. This action is permanent and cannot be undone.
* `create_custom_sql_monitor` — Create a user-defined custom SQL monitor for a dataset.
* `update_custom_sql_monitor` — Update an existing user-defined custom SQL monitor (e.g. SQL query, sensitivity, thresholds, grouping, exclusion zones).
* `delete_custom_sql_monitor` — Delete a user-defined custom SQL monitor. This action is permanent and cannot be undone.
* `run_historical_metric_collection` — Trigger a historical metric collection scan for a dataset. The v4 API calls this a historical metric collection scan; in user-facing terms it backfills metric history so monitors (ML-based anomaly detection) have a baseline to learn from.
Contracts — declarative source-of-truth for checks
A data contract is the declarative source-of-truth for checks on a dataset. Checks (deterministic validations with fixed thresholds) are defined inside contracts, not via this API.
* `list_contracts` — List data contracts in your Soda Cloud organization. A data contract is the declarative source-of-truth for checks on a dataset.
* `create_contract` — Create a new data contract on a dataset. The contract is initialized with the YAML contents you supply; the full contract YAML is normally installed later via `publish_contract`.
* `get_contract` — Retrieve a specific data contract by ID, including its YAML content.
* `publish_contract` — Publish new YAML content for an existing data contract.
* `list_contract_versions` — List published versions of a specific data contract. Each publish creates a new version; this tool returns the version history.
* `verify_contract` — Trigger a contract verification scan for the given contract. Runs the checks defined in the contract against the dataset.
* `create_skeleton_contract` — Trigger async generation of a skeleton contract for a dataset, derived from its warehouse schema. Use this to bootstrap a contract's YAML body when no contract has been published yet.
* `get_skeleton_contract_status` — Get the status of a skeleton contract generation operation started via `create_skeleton_contract`.
* `generate_contracts` — Trigger async AI-powered generation of full contracts for one or more datasets.
* `get_contract_generation_status` — Get the status of a contract generation operation started via `generate_contracts`.
Data Standards — organization-wide YAML policies applied by scope
A data standard is an organization-wide YAML policy whose checks are automatically applied to every dataset matching its scope. This is distinct from a data contract (the per-dataset source-of-truth for one dataset's checks): a standard fans one policy out across many datasets. Running a dataset's active standards produces a scan, observed via the Scans tools.
* `list_data_standards` — List data standards in your Soda Cloud organization. A data standard is an organization-wide YAML policy whose checks are automatically applied to every dataset matching its scope.
* `get_data_standards_activity` — Get an organization-wide rollup of data standards activity, including counts of active and total standards, matched datasets, and aggregated check results.
* `get_data_standard` — Retrieve a specific data standard by ID, including its YAML contents and scope.
* `list_data_standard_checks` — List the aggregated checks generated by a specific data standard across the datasets it matches.
* `list_data_standard_datasets` — List the datasets currently matched by a specific data standard's scope.
* `evaluate_data_standard_scope` — Re-evaluate which datasets currently match a data standard's scope and return their dataset IDs.
* `create_data_standard` — Create a new data standard from YAML contents, a structured scope, status, owners, and an optional schedule. A data standard is an organization-wide YAML policy whose checks are automatically applied to every dataset matching its scope.
* `update_data_standard` — Update an existing data standard's YAML contents, scope, status, owners, and schedule.
* `update_data_standard_status` — Transition a data standard to a new status without modifying its contents, scope, owners, or schedule. Use this to pause or activate an existing standard.
* `delete_data_standard` — Delete a data standard.
* `execute_data_standards` — Trigger a scan that runs the active data standards linked to a dataset. Identify the dataset by `datasetId`.
Datasources — warehouse connections that own datasets
A datasource is a configured connection to a warehouse (e.g. Snowflake, Postgres) that owns datasets.
* `list_datasources` — List datasources in your Soda Cloud organization. A datasource is a configured connection to a warehouse (e.g. Snowflake, Postgres) that owns datasets.
* `run_datasource_discovery` — Trigger a discovery scan on a datasource. Detects new tables and schemas in the warehouse on-demand (instead of waiting for the scheduled cron).
* `create_datasource` — Create a new datasource from a YAML configuration document. The datasource type (e.g. Snowflake, Postgres) is extracted from the YAML contents.
* `get_datasource` — Get a datasource's full configuration by ID, including its YAML configuration, label, runner, and type.
* `update_datasource` — Update a datasource's configuration. Only the fields you supply are updated (PATCH semantics); omitted fields keep their existing values.
* `delete_datasource` — Delete a datasource and all its associated resources (datasets, checks, scans, incidents).
* `list_datasource_roles` — List available datasource roles. Use datasource roles to manage access to individual datasources.
* `create_datasource_role` — Create a custom datasource role.
* `update_datasource_role` — Update the name or permissions of a custom datasource role.
* `delete_datasource_role` — Delete a custom datasource role. This action is permanent and cannot be undone.
* `get_datasource_diagnostics_warehouse` — Get the diagnostics warehouse configuration for a datasource. The diagnostics warehouse collects scan-related data (failed rows, scan results) and forwards it to the customer's warehouse for storage and analysis.
* `update_datasource_diagnostics_warehouse` — Update the diagnostics warehouse configuration for a datasource. The diagnostics warehouse collects scan-related data (failed rows, scan results) and stores it in your warehouse for analysis.
* `list_datasource_responsibilities` — List user and user group permissions assigned to a datasource, and their associated roles.
* `update_datasource_responsibilities` — Update user/group permissions and their associated roles for a datasource.
* `test_datasource_connection` — Trigger an async connection test for a datasource configuration. Use this to validate a YAML + runner combination without creating a datasource, e.g. before calling `create_datasource`.
* `get_datasource_connection_test_status` — Get the status of an async datasource-connection-test operation started via `test_datasource_connection`.
* `onboard_discovered_datasets` — Trigger async onboarding of one or more discovered datasets for a datasource. Onboarding promotes a discovered-but-not-yet-tracked dataset into a regular Soda dataset that can carry contracts, checks, and monitors.
* `get_onboard_discovered_datasets_status` — Get the status of an async dataset-onboarding operation started via `onboard_discovered_datasets`.
Discovered Datasets — tables found by discovery scans
Discovered datasets are tables that Soda has found during a discovery scan but have not yet been onboarded as first-class Soda datasets. Onboarding is driven by `onboard_discovered_datasets` (in the Datasources section).
* `list_discovered_datasets` — List datasets Soda has discovered in your data sources. Discovered datasets have been found during a discovery scan but may not yet be onboarded as first-class Soda datasets.
Runners — execute scans and datasource operations
Runners execute scans and datasource operations. Self-hosted runners require one-time API key credentials created through `create_runner`.
* `list_runners` — List Soda runners in your organization.
* `create_runner` — Create API key credentials for a new self-hosted Soda runner deployment.
* `get_runner` — Get a runner by ID, including online status, runner type, version information, and last-seen timestamp.
* `delete_runner` — Delete a self-hosted runner by ID only after the user has explicitly confirmed deletion.
Secrets — encrypted credentials referenced from datasource YAML
Secrets store credentials that can be referenced from datasource YAML as `${secret.NAME}`. For manual secret entry, use Soda Cloud's Web UI instead of pasting plaintext into an LLM chat. At runtime, the server instructions include the organization-specific secrets page (`/o//scans-and-data/secrets`) so agents can point users there and ask for confirmation before using MCP. First-turn plaintext secret create/update prompts should receive a text-only warning, not an immediate tool call.
If you explicitly confirm MCP-based secret automation, pass the literal plaintext value to `create_secret` / `update_secret`; the MCP server encrypts the value transparently before sending it to Soda Cloud, so plaintext never leaves the local agent process unencrypted. Soda's runner decrypts the value only during scan execution.
* `list_secrets` — List secrets in your organization.
* `create_secret` — Create a new secret that can be referenced in datasource YAML as `${secret.NAME}`.
* `delete_secret` — Delete an existing secret.
* `update_secret` — Update the value of an existing secret. The secret name cannot be changed.
***
{% if visitor.claims.plan === 'datasetStandard' %}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Dataset Standard license** documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
{% endhint %}
{% endif %}
{% if visitor.claims.plan === 'enterprise' %}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Team license** documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
{% endhint %}
{% endif %}
{% if visitor.claims.plan === 'enterpriseUserBased' %}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Enterprise license** documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
{% endhint %}
{% endif %}
{% if !(visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard') %}
{% hint style="info" %}
You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
If you do have a Soda license, make sure to **log in to Soda Cloud in this same browser**.
{% endhint %}
{% endif %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.soda.io/soda-ai/soda-mcp/mcp-tools.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.