> 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.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 allows your team to **fully manage your data** **from inside the AI agents your team already works in**, such as Claude, Cursor, Codex, or GitHub Copilot. `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 > Soda MCP is available for Soda Cloud customers. [Request a free account](https://soda.io/pricing) or [book a call](https://soda.io/pricing) to learn more. > To view the full list of MCP tools, navigate to the [Tools documentation.](/soda-ai/soda-mcp/mcp-tools.md) #### MCP vs. Soda AI Soda MCP connects your own AI agent to supported Soda Cloud operations. [Soda AI chat](/soda-ai.md#chat-interface) provides an agent inside Soda Cloud, 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
Requires enablement"] end ``` | Workflow | Your agent with Soda MCP | Soda AI chat | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Setup** | Configure an MCP-compatible agent with Soda MCP and your Soda Cloud API key. | Nothing to install. Requires Soda AI chat to be enabled. | | **Permissions** | Your API key authorizes your actions, but you are still limited by your permissions. Optionally, you can configure your agent to further limit your access. | Acts as you, with your permissions. | | **Soda AI enablement** | Not required. [Contract Autopilot](/soda-ai/contract-autopilot.md) 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 The server runs as a local stdio MCP process. Your AI client starts `soda-mcp`, passes Soda Cloud credentials through environment variables, and then calls Soda tools through the MCP protocol. On startup, `soda-mcp` authenticates with Soda Cloud and loads organization context so the client can use the exposed tools against the correct tenant. Follow the instructions in this section to install the Soda MCP server for your host client. #### Requirements * Python 3.10+ * [`uv`](https://docs.astral.sh/uv/) python package on `PATH` * A Soda Cloud API key ID and secret * A Soda Cloud host URL If you don't have API keys already you can create them following the instructions [here](/reference/soda-apis/generate-api-keys.md#generate-api-keys-for-use-with-soda-core-or-a-soda-cloud-api). Set the runtime environment variables before starting the server: ```bash export SODA_CLOUD_HOST="cloud.soda.io" export SODA_API_KEY_ID="your-key-id" export SODA_API_KEY_SECRET="your-key-secret" ``` :exclamation: **Note:** If you are using Windows without WSL you will need to modify the commands to work with either the Windows command prompt: ```shellscript set SODA_CLOUD_HOST=cloud.soda.io set SODA_API_KEY_ID=your-key-id set SODA_API_KEY_SECRET=your-key-secret ``` or Windows Powershell: ```powershell $env:SODA_CLOUD_HOST = "cloud.soda.io" $env:SODA_API_KEY_ID = "your-key-id" $env:SODA_API_KEY_SECRET = "your-key-secret" ``` You will also need to modify the commands of the following sections as is appropriate. #### Install from Soda's private PyPI Stable releases are published to Soda's private PyPI indexes for Team and Enterprise customers. Choose the private index that matches your license and region, then set `UV_INDEX` using the same Soda API key credentials:
LicenseRegionIndex URL
TeamEUhttps://team.pypi.cloud.soda.io
TeamUShttps://team.pypi.us.soda.io
EnterpriseEUhttps://enterprise.pypi.cloud.soda.io
EnterpriseUShttps://enterprise.pypi.us.soda.io
Pick the appropriate command below according to your plan and region. Note that this command depends on the Soda API key environment variables mentioned above in order to execute successfully. Pick the proper one according to your plan and region: {% tabs %} {% tab title="Team EU" %} {% code overflow="wrap" %} ```bash export UV_INDEX="https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@team.pypi.cloud.soda.io" ``` {% endcode %} {% endtab %} {% tab title="Team US" %} {% code overflow="wrap" %} ```bash export UV_INDEX="https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@team.pypi.us.soda.io" ``` {% endcode %} {% endtab %} {% tab title="Enterprise EU" %} {% code overflow="wrap" %} ```bash export UV_INDEX="https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@enterprise.pypi.cloud.soda.io" ``` {% endcode %} {% endtab %} {% tab title="Enterprise US" %} {% code overflow="wrap" %} ```bash export UV_INDEX="https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@enterprise.pypi.us.soda.io" ``` {% endcode %} {% endtab %} {% endtabs %} Smoke-test that `uvx` can resolve and start the package: 
timeout 10s uvx -qq --no-progress soda-mcp@latest
If everything is set up correctly you will see the following output: ``` Authenticated as FirstName LastName (userEmail@soda.io) in org Soda TestOrg Starting soda-mcp server (base_url=https://cloud.soda.io) ``` #### Configure an MCP client Configure your MCP client to start `soda-mcp` over stdio and pass the required environment variables to the child process. For **Claude Code:** ```bash claude mcp add soda-mcp \ --transport stdio \ --scope user \ -e SODA_CLOUD_HOST="$SODA_CLOUD_HOST" \ -e SODA_API_KEY_ID="$SODA_API_KEY_ID" \ -e SODA_API_KEY_SECRET="$SODA_API_KEY_SECRET" \ -e UV_INDEX="$UV_INDEX" \ -- uvx -qq --no-progress soda-mcp@latest ``` For **OpenCode**, add a local MCP server entry to your user-scope `opencode.jsonc`: ```jsonc { "mcp": { "soda-mcp": { "type": "local", "command": [ "env", "SODA_CLOUD_HOST=", "SODA_API_KEY_ID=", "SODA_API_KEY_SECRET=", "UV_INDEX=", "uvx", "-qq", "--no-progress", "soda-mcp@latest" ] } } } ``` For a generic stdio MCP client: ```json { "mcpServers": { "soda-mcp": { "command": "uvx", "args": ["-qq", "--no-progress", "soda-mcp@latest"], "env": { "SODA_CLOUD_HOST": "", "SODA_API_KEY_ID": "", "SODA_API_KEY_SECRET": "", "UV_INDEX": "" } } } } ``` If you installed from a local wheel, replace the `uvx -qq --no-progress soda-mcp@latest` command with `soda-mcp` in your client configuration. #### Verify the server After configuring the client, confirm that `soda-mcp` appears in the client's MCP server list and is connected. Then invoke a low-cost read tool such as `list_attributes`. A successful response confirms that: * The MCP client can start the server. * Soda Cloud credentials are reaching the server. * Authentication succeeds against the configured Soda Cloud tenant. * The client can see and call the registered Soda tools. ### 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 Autopoilot 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 While you can create and update secrets through the MCP client it is not recommended to do so. For long lived secrets prefer to create them from the Web User Interface. MCP servers expose tools and instructions on how to user 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 * If `uvx` cannot resolve `soda-mcp`, confirm `UV_INDEX` is set in the MCP client's environment and points at the correct private index. * If private PyPI returns `401` or `403`, confirm the API key ID and secret are valid for the selected Team or Enterprise index. * If startup fails with missing credential errors, confirm the MCP client passes `SODA_API_KEY_ID`, `SODA_API_KEY_SECRET`, and `SODA_CLOUD_HOST` . * If Soda Cloud authentication fails, confirm the API key belongs to the same tenant as the configured host or URL. * If the client does not show any tools, refresh or restart the MCP client so it reconnects and reloads tool descriptions.
*** {% hint style="info" %} You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [Licensing & documentation access](/reference/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-ai/soda-mcp.md?ask=&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.