> 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/connect-remotely.md).

# Connect remotely

Connect your AI client to Soda MCP with your Soda Cloud login.

Connect to Soda MCP with your Soda Cloud account. Remote access is available to Soda v4 users and requires no local server, Python, private package index, or API keys.

The steps below configure Claude Code for your own user account, across projects on this machine. Start with [Claude Code installed](https://code.claude.com/docs/en/setup) and access to your Soda Cloud organization.

{% hint style="warning" %}
Soda MCP includes tools that create, update, and delete resources or start scans. Actions remain limited by your Soda Cloud permissions. Review proposed tool calls before approving them.
{% endhint %}

## Connect Claude Code

{% stepper %}
{% step %}

### Choose your region

Use the region where you sign in to Soda Cloud. If you are unsure, check your Soda Cloud browser address rather than guessing.

| Region        | Soda Cloud address         | MCP server URL                 |
| ------------- | -------------------------- | ------------------------------ |
| EU            | `https://cloud.soda.io`    | `https://cloud.soda.io/mcp`    |
| US            | `https://cloud.us.soda.io` | `https://cloud.us.soda.io/mcp` |
| {% endstep %} |                            |                                |

{% step %}

### Add your connection

In the terminal where you run Claude Code, inspect existing connections first:

```bash
claude mcp list
```

If Soda is already configured, inspect that entry with `claude mcp get <name>`. Reuse it if it has the correct URL and user scope; continue to sign-in. If it uses local stdio, a different region, or another scope, follow [Existing connections](#existing-connections) before adding anything. Check for Soda entries under other names or installed plugins too.

If no Soda connection exists, run only the command for your region:

{% tabs %}
{% tab title="EU" %}

```bash
claude mcp add --transport http --scope user soda-mcp https://cloud.soda.io/mcp
```

{% endtab %}

{% tab title="US" %}

```bash
claude mcp add --transport http --scope user soda-mcp https://cloud.us.soda.io/mcp
```

{% endtab %}
{% endtabs %}

`--scope user` keeps this configuration personal. Do not add it to a shared project configuration or change organization-wide settings. The same single-line command works in Bash, PowerShell, and Windows Command Prompt; run it on the host where your client runs, including inside WSL if applicable.
{% endstep %}

{% step %}

### Sign in

Start or restart your Claude Code session, then enter:

```
/mcp
```

Select your Soda connection (`soda-mcp` if added above) and follow the authentication flow. Sign in to Soda Cloud in your browser and review the consent request yourself. Use the normal OAuth login and consent flow; do not add API key headers. If the browser does not open, open the URL Claude Code provides. Return to Claude Code after consent.
{% endstep %}

{% step %}

### Verify your connection

In `/mcp`, confirm that your Soda connection (`soda-mcp` if added above) is connected. Then ask Claude Code:

```
Use Soda MCP to call list_datasets with page 0 and size 10. Report whether the call succeeds without changing any resources.
```

A successful dataset response, including an empty result, confirms a working Cloud-backed connection. Seeing tools in the list is not enough. A tool error, including `isError: true` inside an HTTP 200 response, means verification failed.
{% endstep %}
{% endstepper %}

> Continue with the shared [MCP tools reference](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/mcp-tools.md). `create_secret`, `update_secret`, and `create_runner` are local-only.

## Setup prompt

Copy this prompt into the AI client you want to configure. The client must support remote HTTP MCP and OAuth; this is general setup guidance, not a compatibility guarantee for every client.

{% code overflow="wrap" %}

```
Set up remote Soda MCP for this client and my personal user account using https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/connect-remotely. Adapt to my host and shell. Inspect existing Soda connections, preserve unrelated configuration, and avoid duplicates. Ask which Soda region I use if unclear; never guess. Make only the necessary setup changes, minimizing manual steps. Let me complete login and consent myself. Verify with a successful read-only tool call and report the result. Do not change shared or organization settings or install unrelated software. Offer local fallback only if necessary and after my confirmation, not for transient failures. If tools or client support are unavailable, give minimal next steps without claiming success.
```

{% endcode %}

## Existing connections

Do not silently overwrite an existing registration or leave both local and remote Soda connections active. Confirm the intended change before replacing or disabling a connection. Preserve unrelated entries and keep a recoverable copy of the entry you change, without exposing its credentials. A same-name entry in local or project scope takes precedence over user scope.

For an existing personal user-scoped entry named `soda-mcp`, once you have confirmed replacement, remove only that entry, then add the remote connection above:

```bash
claude mcp remove soda-mcp --scope user
```

For a plugin-managed or shared entry, use the client's supported controls to disable it for your own use, or ask your administrator if personal changes are restricted. Do not alter shared configuration as part of this setup.

## Troubleshooting

* **Authentication required:** open `/mcp` and complete sign-in for the configured Soda connection. Confirm that the endpoint matches your Soda Cloud region.
* **Permission denied:** the tool still requires the corresponding Soda Cloud permissions. Ask your Soda administrator if you need additional access.
* **Connection timeout or service error:** retry later without changing your region, deleting valid credentials, or switching automatically to local setup.
* **Unsupported client or no execution tools:** follow that client's personal remote HTTP MCP and OAuth setup instructions, using the URL above. If it cannot connect remotely, consider [Run locally](https://docs.soda.io/soda-documentation/soda-ai/soda-mcp/run-locally.md) only after confirming that alternative and its prerequisites.

> For client-specific details, see the [Claude Code MCP reference](https://code.claude.com/docs/en/mcp).

<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/connect-remotely.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.
