> 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/run-locally.md).

# Run locally

Run Soda MCP locally with your Soda Cloud API keys.

Run Soda MCP locally if you need control over the MCP server and its security configuration. For the recommended setup without Python, package installation, or API keys, [connect remotely](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/connect-remotely.md).

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.11+
* [`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](https://docs.soda.io/apis/generate-api-keys.md).

Set the runtime environment variables before starting the server. Use `cloud.soda.io` for EU or `cloud.us.soda.io` for US; the examples below use EU:

```bash
export SODA_CLOUD_HOST="cloud.soda.io"
export SODA_API_KEY_ID="your-key-id"
export SODA_API_KEY_SECRET="your-key-secret"
```

<i class="fa-exclamation" style="color:$warning;">:exclamation:</i> **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:

<table><thead><tr><th width="138.66665649414062">License</th><th width="122.16668701171875">Region</th><th>Index URL</th></tr></thead><tbody><tr><td>Team</td><td>EU</td><td><code>https://team.pypi.cloud.soda.io</code></td></tr><tr><td>Team</td><td>US</td><td><code>https://team.pypi.us.soda.io</code></td></tr><tr><td>Enterprise</td><td>EU</td><td><code>https://enterprise.pypi.cloud.soda.io</code></td></tr><tr><td>Enterprise</td><td>US</td><td><code>https://enterprise.pypi.us.soda.io</code></td></tr></tbody></table>

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. Stop the server with `Ctrl-C` after startup:

```bash
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.

Before adding a connection, inspect your client's existing Soda registrations. Reuse a suitable connection; do not silently replace one or leave duplicate active connections. Preserve unrelated settings when editing configuration.

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=<host>",
        "SODA_API_KEY_ID=<key-id>",
        "SODA_API_KEY_SECRET=<key-secret>",
        "UV_INDEX=<private-index-url-with-auth>",
        "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": "<host>",
        "SODA_API_KEY_ID": "<key-id>",
        "SODA_API_KEY_SECRET": "<key-secret>",
        "UV_INDEX": "<private-index-url-with-auth>"
      }
    }
  }
}
```

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

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

> For available tools and usage guidance, see [MCP tools](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/mcp-tools.md) and [Soda MCP](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp.md#usage-instructions).

<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) or <a href="https://docs.soda.io/~gitbook/auth/login" class="button primary small">Log in to Soda Cloud</a>.
{% 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/run-locally.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.
