> 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-documentation/soda-ai/soda-mcp.md).

# Soda MCP

Use Soda from your preferred AI agent.

{% hint style="info" %}
**The MCP server does not require Soda AI enablement**. It provides agentic access to the Soda Cloud API, meaning your organization can use it without enabling Soda AI features.

The MCP will not be able to reach the capabilities that depend on Soda AI if the latter is not enabled.
{% endhint %}

Soda MCP is available to Soda v4 users. Connect your AI client to Soda Cloud to inspect datasets and checks, manage contracts, and work with other data quality resources.

[Connect remotely](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/connect-remotely.md) for the recommended setup: sign in with your Soda Cloud account, without installing a server or creating API keys. [Run locally](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/run-locally.md) if you need control over the MCP server and its security configuration.

`soda-mcp` is a Model Context Protocol (MCP) server for Soda Cloud. **It lets MCP-capable AI clients use Soda Cloud's public API** to inspect and manage data quality resources such as datasets, checks, contracts, scans, monitors, incidents, attributes, data sources, users, and user groups.

Reach for Soda MCP **when you want an AI agent to help with data workflows**, for example:

* **List datasets** and **inspect** their health status.
* **Retrieve** checks, contracts, scans, and incidents.
* **Create** or **update** contracts and monitors.
* **Trigger** discovery, contract verification, historical metric collection, or other supported Soda Cloud actions.
* **Manage** **Soda Cloud resources** such as attributes, roles, users, and user groups.
* **Build complex workflows** across your entire AI layer, connecting to other agents and MCPs

> To view the full list of MCP tools, navigate to the [Tools documentation.](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/mcp-tools.md)

#### MCP vs. Soda AI Agent <a href="#mcp-vs.-soda-ai" id="mcp-vs.-soda-ai"></a>

Soda MCP connects your own AI agent to supported Soda Cloud operations. [Soda AI Agent](https://docs.soda.io/soda-documentation/soda-ai/soda-ai-agent.md) provides an agent inside Soda Cloud via a chat, combining supported Cloud actions with Soda documentation and applicable webpage context. Their capabilities overlap, but their tools and execution environments differ.

```mermaid
flowchart TB
    own["Your AI agent"] --> mcp["Soda MCP"]
    chat["Soda AI chat in Soda Cloud"] --> agent["Soda AI agent"]
    agent --> embedded["Embedded MCP tools"]
    agent --> docs["Soda documentation retrieval"]
    agent --> page["Webpage context and UI integration"]
    mcp --> operations
    embedded --> operations
    subgraph operations["Supported Soda Cloud operations"]
        standard["Datasets, contracts, checks, and more"]
        autopilot["Contract Autopilot<br/>Requires enablement"]
    end
```

| Workflow               | Your agent with Soda MCP                                                                                                          | Soda AI chat                                                                                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup**              | Connect remotely with your Soda Cloud login, or run locally with API keys.                                                        | Nothing to install. Requires Soda AI chat to be enabled.                                                                                  |
| **Permissions**        | Remote access uses your signed-in Soda Cloud permissions; local access uses the permissions associated with your API key.         | Acts as you, with your permissions.                                                                                                       |
| **Soda AI enablement** | Not required. Contract Autopilot requires enablement; other MCP operations remain available.                                      | Required.                                                                                                                                 |
| **Background work**    | Enables scheduled, parallel, and background work through your agent or orchestration system.                                      | Supports concurrent conversations and continued responses while the panel is hidden. Does not provide durable unattended agent execution. |
| **Product guidance**   | Depends on your agent and connected tools. Includes contract and data-standard authoring guidance, but no general Soda Q\&A tool. | Retrieves Soda documentation and uses applicable webpage context.                                                                         |

### Installation instructions

Choose [Connect remotely](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/connect-remotely.md) for the recommended setup, or [Run locally](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/run-locally.md) for the local alternative.

#### Requirements

See [local requirements](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/run-locally.md#requirements).

#### Install from Soda's private PyPI

See [private package installation](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/run-locally.md#install-from-sodas-private-pypi).

#### Configure an MCP client

See [local client configuration](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/run-locally.md#configure-an-mcp-client).

#### Verify the server

See [local server verification](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/run-locally.md#verify-the-server).

### Usage instructions

#### Use the tools

Once connected, ask your AI client to perform Soda Cloud tasks naturally. Examples:

```
List the datasets in my Soda Cloud organization and summarize unhealthy datasets.
```

```
Can you show me the latest failing checks?
```

```
Verify the contract for the dataset datasource/database/schema/table
```

```
Use Contract Autopilot to create a contract for the dataset datasource/database/schema/table
```

Some tools modify Soda Cloud resources or trigger scans. Review the client's proposed tool call before approving write, delete, or trigger actions.

#### Usage notes

`create_secret`, `update_secret`, and `create_runner` are available only when you [run locally](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/run-locally.md). For long-lived secrets, prefer the Soda Cloud Web UI so plaintext stays out of chat history. See the [shared tools reference](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/mcp-tools.md).

MCP servers expose tools and instructions on how to use them. Some MCP clients, like Codex and OpenCode, do not load the instructions, only the tools. This may affect performance. Claude Code loads both tools and instructions.

#### Troubleshooting

See [remote connection troubleshooting](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/connect-remotely.md#troubleshooting) or [local server troubleshooting](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/run-locally.md#troubleshooting).

<br>

***

{% hint style="info" %}
You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [Licensing & documentation access](https://docs.soda.io/soda-documentation/govern/security-licensing-and-compliance/documentation-access-and-licensing.md).
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.soda.io/soda-documentation/soda-ai/soda-mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
