Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 and access to your Soda Cloud organization.

Connect Claude Code

1

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

2

Add your connection

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

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 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:

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

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

3

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.

4

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.

Continue with the shared MCP tools reference. 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.

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.

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:

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 only after confirming that alternative and its prerequisites.

For client-specific details, see the Claude Code MCP reference.


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

Last updated

Was this helpful?