> 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 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 {% if !(visitor.claims.plan === %} > 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. > {% endif %} {% if visitor.claims.plan === %} > To view the full list of MCP tools, navigate to the [Tools documentation.](broken://pages/jCHplp9NkfS0uNHxgBgL) > {% endif %} #### MCP vs. Soda AI ​[Soda AI](https://app.gitbook.com/o/ig9n9VJPAFRSFLtZKVB2/s/A2PmHkO5cBgeRPdiPPOG/~/diff/~/changes/673/soda-mcp) and Soda MCP **both let you work with Soda Cloud through natural language**, and they overlap on what they can do, but **they suit different jobs**. * **Soda MCP** is the choice for **automated, scheduled, parallel, and background** workflows. Because it runs inside your own tooling you can build cron, parallelism, and completion notifications around it. * **Soda AI**, on the other hand, is a **conversational tool for one-off work**, like drafting a contract, or asking what an incident means, while you're on the loop. | Workflow | Soda MCP | Soda AI | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | **Scheduled runs** | Wire MCP-driven tasks into a cron job or pipeline so they run unattended on a schedule. | Soda AI is designed to run only when you're in a session with it, in order to confirm actions. | | **Parallel work** | MCP tasks can fan out across many datasets or datasources at once, driven by your own orchestration. | Soda AI works through one interactive flow and does not orchestrate tasks, it keeps you in the loop. | | **Background execution with notifications** | A long-running MCP job can run in the background and ping you through whatever tooling you've wired up (Slack, email, your pipeline's own alerts) when it finishes. | Soda AI completes the API call but won't notify you when a background-style job is done. | In short: **use Soda AI for interactive, human-in-the-loop work**, and **Soda MCP** when you want the same kinds of actions **to** **run on a schedule, in parallel, or in the background** as part of an automated workflow. {% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard' %} ### 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](broken://pages/H6Piqnv5lUFCAv1Cvm75#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. {% endif %} {% if visitor.claims.plan === %} ### 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 craete 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. {% endif %} *** {% 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.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.