Discover the New Soda AI – MCP, Autopilot, CLI |
Learn More
Ctrlk
Soda CloudBook a demo
slack
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 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 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, installed and logged in. Refer to the Claude Code setup instructions.

  • uv 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.

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.

Creating incidents and publishing RCA reports from the agent requires the incident RCA feature to be enabled for your organization. Contact support@soda.io to enable it.

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.

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.

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 installed with its Windows installer or with WinGet.

  • uv, 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, 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:

Setting the variables in the window this way keeps your API key out of your PowerShell profile. They apply to the current window only.

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:

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.

  • 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.

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.

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 from the repository and run it. It checks every registration, starts soda-mcp, and runs the hook and the skill scripts:

To connect the orchestrator, warehouse, and transformation project the agent investigates with, refer to Connect your data stack.

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

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 support@soda.io 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.

You are not logged in to Soda and are viewing the default public documentation. Learn more about Licensing & documentation access.

If you do have a Soda license, make sure to log in to Soda Cloud in this same browser.

PreviousRoot cause analysis (RCA) agent
NextConnect your data stack

Last updated

Was this helpful?