> 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/rca-agent/install-the-soda-plugin.md). # Install the Soda plugin Install the Soda plugin for Claude Code, which brings the /rca and /create-incident skills together with the Soda MCP server. The Soda plugin for Claude Code brings the `/rca` and `/create-incident` skills to your Claude Code sessions, together with the [Soda MCP](/soda-documentation/soda-ai/soda-mcp.md) server. Both are installed from Soda's private package index, entitled by your Soda Cloud API key. The installer lives in the public [sodadata/soda-agentic-tools](https://github.com/sodadata/soda-agentic-tools) repository as two short scripts: `install.sh` for macOS, Linux, and Windows inside WSL 2, and `install.ps1` for native Windows. Both are kept short so that you can audit them before running them. ## Prerequisites * [Claude Code](https://claude.com/claude-code), installed and logged in. Refer to the [Claude Code setup instructions](https://code.claude.com/docs/en/setup). * [`uv`](https://docs.astral.sh/uv/getting-started/installation/) on your `PATH`. * Python 3.8 or newer on your `PATH`: `python3` on macOS and Linux, `python` on Windows. The skills run Python scripts. * A Soda Cloud API key that is entitled for Soda's private package index. Create one in Soda Cloud under your avatar > **Profile** > **API Keys** > **+**. Refer to [Generate API keys](broken://pages/H6Piqnv5lUFCAv1Cvm75). The installer supports these platforms: | Platform | Supported | Installer | | --------------------- | ---------------------------------- | ----------------------------------------- | | macOS | 13 or later | `install.sh` | | Linux | Ubuntu 20.04+, Debian 10+, RHEL 8+ | `install.sh` | | Windows, inside WSL 2 | Windows 11 23H2 or later | `install.sh`, run in the WSL distribution | | Windows, native | Windows 11 23H2 or later, ARM64 | `install.ps1` | On x64 Windows, use WSL 2. Windows 10 is out of Microsoft support and is not supported. {% hint style="info" %} Creating incidents and publishing RCA reports from the agent requires the incident RCA feature to be enabled for your organization. Contact to enable it. {% endhint %} ## Install Run the installer from any directory, passing your credentials as environment variables. The installer reads them from the environment and never writes them to a file. {% tabs %} {% tab title="macOS/Linux" %} {% code overflow="wrap" %} ```bash SODA_CLOUD_HOST=cloud.soda.io \ SODA_API_KEY_ID= \ SODA_API_KEY_SECRET= \ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/sodadata/soda-agentic-tools/main/claude/install.sh)" ``` {% endcode %} Prefixing the command this way keeps your API key out of your shell profile and out of your shell history. On Windows inside WSL 2, run the same command in your WSL distribution. {% endtab %} {% tab title="Windows" %} Claude Code runs on Windows either inside WSL 2 or natively, and the plugin follows Claude Code. WSL 2 is recommended when your IT allows it: it uses the macOS/Linux installer unchanged, and it is the only route where Claude Code's sandboxing works. The native installer supports Windows 11 23H2 or later on ARM64. Native Windows needs, on top of the prerequisites above: * [Claude Code](https://code.claude.com/docs/en/setup) installed with its Windows installer or with WinGet. * [`uv`](https://docs.astral.sh/uv/getting-started/installation/), installed with `irm https://astral.sh/uv/install.ps1 | iex`. * Python 3.8 or newer as `python` on your `PATH`, installed with `winget install Python.Python.3.12` or the python.org installer. If typing `python` opens the Microsoft Store, turn off the Python entries under **Settings** > **Apps** > **Advanced app settings** > **App execution aliases**. That alias is a stub, not an interpreter, and the installer refuses it. * [Git for Windows](https://git-scm.com/downloads/win), recommended. It gives Claude Code a Bash tool. Without it, Claude Code runs the skills' commands through PowerShell, which the skills support but which is less rehearsed. Then, in PowerShell 5.1 or 7, from any directory: ```powershell $env:SODA_CLOUD_HOST = "cloud.soda.io" $env:SODA_API_KEY_ID = "" $env:SODA_API_KEY_SECRET = "" irm https://raw.githubusercontent.com/sodadata/soda-agentic-tools/main/claude/install.ps1 | iex ``` Setting the variables in the window this way keeps your API key out of your PowerShell profile. They apply to the current window only. {% endtab %} {% endtabs %} Set `SODA_CLOUD_HOST=cloud.us.soda.io` for the US region. The installer defaults to the Team EU package index. If your license or region differs, also set `SODA_PYPI_INDEX`: | License | Region | `SODA_PYPI_INDEX` | | ---------- | ------ | ----------------------------------- | | Team | EU | `team.pypi.cloud.soda.io` (default) | | Team | US | `team.pypi.us.soda.io` | | Enterprise | EU | `enterprise.pypi.cloud.soda.io` | | Enterprise | US | `enterprise.pypi.us.soda.io` | The script checks the prerequisites and your credentials, prints exactly what it is going to do, and asks once before changing anything. Afterwards, restart Claude Code: skills load at session start. ### What the script does On approval, the script runs the following commands, with `UV_INDEX` pointing at the private index for the duration of the install only: ```bash # 1. Install soda-mcp as a uv tool, so the index is not needed at session start uv tool install --force soda-mcp # 2. Register it with Claude Code by absolute path, carrying your Soda Cloud credentials claude mcp add soda-mcp --transport stdio --scope user \ -e SODA_CLOUD_HOST=... -e SODA_API_KEY_ID=... -e SODA_API_KEY_SECRET=... \ -- "$(uv tool dir --bin)/soda-mcp" # 3. Fetch the plugin and let it unpack itself into ~/.soda/claude-plugins/soda, # register that directory as a local marketplace, and install the plugin from it uvx soda-plugin@latest install ``` Everything installs at the user level: uv's tool directory, `~/.soda`, and your Claude Code configuration. Nothing is written into the directory you run the command from, and your shell profile is not modified. On native Windows, the PowerShell installer does the same things in the same order, with these differences: * It refuses to run below the supported Windows floor. Refer to `SODA_INSTALL_ALLOW_UNSUPPORTED_OS` in the environment variables below. * It sets `UV_NATIVE_TLS=true` for the duration of the install, so that `uv` trusts the Windows certificate store. This is what makes the downloads work behind a corporate proxy that inspects TLS with its own root CA. Claude Code itself follows the system proxy and certificate settings. Refer to the [Claude Code network configuration](https://code.claude.com/docs/en/network-config). * `soda-mcp` is installed as `soda-mcp.exe` in uv's tool directory, `%USERPROFILE%\.local\bin` by default, and the plugin under `%USERPROFILE%\.soda\claude-plugins\soda`. Claude Code keeps its own copy under `%USERPROFILE%\.claude\plugins\cache`. If your endpoint policy, such as AppLocker or WDAC, blocks executables under the user profile, these are the paths to allow. `soda-mcp.exe` is a launcher generated by `uv` and is not code-signed. * The plugin's Stop hook is stamped with the absolute path of the Python interpreter found at install time, because Windows has no `python3` command. Re-run the installer after moving or upgrading Python. * `soda-mcp` is installed under a uv-managed x64 Python, which Windows runs through its x64 emulation, because one of its dependencies, `cryptography`, publishes no ARM64 wheel. `uv` downloads that Python once, about 30 MB. Everything else, including the plugin's scripts, stays native. * No PowerShell profile and no `PATH` entry is modified. Your credentials are never written to a file by the script. They end up in exactly one place: the `env` block of the `soda-mcp` entry in your Claude Code configuration. The `/create-incident` skill reads them from there, so there is a single copy to rotate or revoke. {% hint style="warning" %} Avoid running `claude mcp get soda-mcp` in a shared terminal or inside an agent session. It prints the API key secret in plain text. {% endhint %} ## Check the install Start a Claude Code session and run these commands inside it: * `/plugin` opens the plugin manager. `soda` is listed as installed and enabled, with the `rca` and `create-incident` skills. * `/mcp` lists the MCP servers. `soda-mcp` shows as connected. The skills are available as `/rca` and `/create-incident`. On native Windows, you can also check the install without starting a session. Download [`verify.ps1`](https://github.com/sodadata/soda-agentic-tools/blob/main/claude/verify.ps1) from the repository and run it. It checks every registration, starts `soda-mcp`, and runs the hook and the skill scripts: ```powershell irm https://raw.githubusercontent.com/sodadata/soda-agentic-tools/main/claude/verify.ps1 -OutFile verify.ps1 powershell -ExecutionPolicy Bypass -File .\verify.ps1 ``` > To connect the orchestrator, warehouse, and transformation project the agent investigates with, refer to [Connect your data stack](/soda-documentation/soda-ai/rca-agent/connect-your-data-stack.md). ## Update Re-run the install command. It is idempotent and upgrades both `soda-mcp` and the plugin to the current release. ## Rotate an API key Re-run the install command with the new key. It replaces the existing `soda-mcp` registration. ## Uninstall {% tabs %} {% tab title="macOS/Linux" %} {% code overflow="wrap" %} ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/sodadata/soda-agentic-tools/main/claude/uninstall.sh)" ``` {% endcode %} {% endtab %} {% tab title="Windows" %} ```powershell irm https://raw.githubusercontent.com/sodadata/soda-agentic-tools/main/claude/uninstall.ps1 | iex ``` {% endtab %} {% endtabs %} The script reports what it finds, asks once, then removes the plugin, the local marketplace, the `soda-mcp` registration, the `soda-mcp` tool, and the plugin directory under `~/.soda/claude-plugins`. ## Environment variables | Variable | Required | Default | Purpose | | ----------------------------------- | -------- | ------------------------- | --------------------------------------------------------------------- | | `SODA_CLOUD_HOST` | yes | | Your Soda Cloud host: `cloud.soda.io` (EU) or `cloud.us.soda.io` (US) | | `SODA_API_KEY_ID` | yes | | Soda Cloud API key ID | | `SODA_API_KEY_SECRET` | yes | | Soda Cloud API key secret | | `SODA_PYPI_INDEX` | no | `team.pypi.cloud.soda.io` | The private package index for your license and region | | `SODA_PYPI_API_KEY_ID` | no | `SODA_API_KEY_ID` | Use a different key for the package index than for Soda Cloud | | `SODA_PYPI_API_KEY_SECRET` | no | `SODA_API_KEY_SECRET` | As above | | `SODA_INSTALL_NONINTERACTIVE` | no | | Set to `1` to skip the confirmation prompt, for agents and CI | | `SODA_UNINSTALL_NONINTERACTIVE` | no | | The same, for the uninstall script | | `SODA_INSTALL_ALLOW_UNSUPPORTED_OS` | no | | Windows only. Set to `1` to install below the supported Windows floor | ## Troubleshooting | Symptom | Cause and fix | | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401`, `403`, or a resolution error from the index | The API key is revoked or not entitled, or `SODA_PYPI_INDEX` is wrong for your license and region. Verify the key in Soda Cloud and check the index table above. | | `/rca` or `/create-incident` is not available | Restart Claude Code. Skills load at session start. | | `/create-incident` reports that `soda-mcp` is not registered | Re-run the installer, then restart Claude Code. The skill reads its credentials from the `soda-mcp` registration. | | `/create-incident` reports that the incident RCA feature is not enabled | The feature is off for your organization. Contact to enable it. | | Windows: `this Windows release is not supported` | The installer refuses Windows releases below Windows 11 23H2, build 22631. Update Windows, or set `SODA_INSTALL_ALLOW_UNSUPPORTED_OS=1` to install anyway, at your own risk. | | Windows: `no working 'python'` | `python` on your `PATH` is the Microsoft Store stub, or Python is missing. Install Python 3.8 or newer and turn off the Python app execution aliases. Refer to the Windows tab under Install. | | Windows: certificate or TLS errors from `uv` behind a corporate proxy | The installer already sets `UV_NATIVE_TLS`. If the download still fails, the proxy's root CA is not in the Windows certificate store. Ask your IT department. | | Windows: the follow-up picker never appears after `/rca` | The Stop hook's interpreter path is stale because Python moved or was upgraded. Re-run the installer. |
*** {% hint style="info" %} You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [Licensing & documentation access](/soda-documentation/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-documentation/soda-ai/rca-agent/install-the-soda-plugin.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.