How to add a remote MCP server to any AI client

By Killian, founder · Updated 27 October 2026 · Markdown

A remote MCP server is a URL, not a program you install. To add one to an AI client you give the client that URL, pick the HTTP transport (also called Streamable HTTP), and sign in when the client asks. Clients that support OAuth find the sign-in page from the URL by themselves, so there is usually no key to paste. The exact place you type the URL differs per client, and that’s what this page lists.

The examples use https://app.datatomcp.com/mcp, a hosted MCP server that lets an agent query your CSVs and Google Sheets. Swap in any other server’s URL; the steps are the same.

The short version for every client

What you need to know before you start

Transport. New servers use Streamable HTTP: one URL, usually ending in /mcp. Older servers used SSE (a URL often ending in /sse). Most clients now try HTTP first and fall back to SSE. If a client asks you to pick, pick HTTP unless the server’s docs say SSE.

Sign-in: OAuth or a header. A server either signs you in with OAuth (the client opens a browser window, you log in and approve access) or expects a fixed header such as Authorization: Bearer <token>. OAuth servers publish their sign-in details at a well-known address, and clients that support dynamic client registration set themselves up without a client ID. If you add an Authorization header to an OAuth server, many clients send the header and never start the sign-in, so leave headers out unless the server’s docs ask for them.

Scope. Most clients let you add a server for one project (a file in the repo, shareable with your team) or for your user account (every project). Put team-shared servers in the project file and personal ones in the user file. Never commit tokens to a project file; use the client’s environment-variable syntax instead.

Tool budget. Every server adds tool descriptions to the model’s context. Some clients cap the total (Devin Desktop documents 100 tools). Turn off servers you aren’t using.

How to check it worked

1. Look at the client’s server list. Claude Code, Codex, OpenCode and Gemini CLI each have an mcp list command; the desktop apps show a status dot or toggle.
2. Make sure the tools are listed. A server that connects but shows zero tools usually failed sign-in.
3. Ask for something only that server can answer, and name it the first time: “Use datatomcp to list my datasets.” The client should show a tool call and its result.

Common errors

• 401 Unauthorized or “needs authentication”. You haven’t signed in yet, or the token expired. Run the client’s auth command or click its Authenticate/Connect button.
• The sign-in page never opens. Check that you didn’t add an Authorization header by hand. Remove it and reconnect.
• “Failed to connect” right away. Wrong transport (SSE vs HTTP) or a typo in the URL. Open the URL in a browser: an MCP endpoint usually answers with an error message, not a 404.
• Connected, but the model ignores the tools. Mention the server by name in the prompt, and check the server is enabled for that chat or agent.
• Works on your laptop, fails in a web app. Web clients such as Claude.ai and ChatGPT connect from their own servers, so the MCP server must be reachable on the public internet.

Windsurf (Devin Desktop)

Windsurf was renamed Devin Desktop in 2026. Open the … menu at the top right of the Cascade panel and click Open MCP config file in the MCPs section. The file is ~/.config/devin/mcp_config.json on macOS and Linux and %APPDATA%\devin\mcp_config.json on Windows (older installs used ~/.codeium/windsurf/mcp_config.json). Remote servers use serverUrl:

{
  "mcpServers": {
    "datatomcp": { "serverUrl": "https://app.datatomcp.com/mcp" }
  }
}

Save, then sign in when the browser opens. Cascade has a limit of 100 tools across all servers, and team admins can restrict which servers are allowed.

Gemini CLI

gemini mcp add --transport http -s user datatomcp https://app.datatomcp.com/mcp

Without -s user the server is saved to the project’s .gemini/settings.json. Start gemini, run /mcp auth datatomcp to sign in, and /mcp list to see the tools. Google moved free-tier users from Gemini CLI to Antigravity CLI in June 2026; if that’s you, see the Antigravity guide.

Clients that only run local servers: mcp-remote

Some clients can only start a local process (stdio). mcp-remote is a small bridge that runs locally, talks to the remote URL and handles the OAuth sign-in in your browser:

{
  "mcpServers": {
    "datatomcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.datatomcp.com/mcp"]
    }
  }
}

It needs Node.js. Use it only when the client has no remote option; a native remote connection is simpler to debug.

A worked example: let any client query a spreadsheet

The server in these examples, datatomcp, turns a CSV or Google Sheet into five read-only tools: list_datasets, describe_dataset, query_rows, aggregate and distinct_values. The agent sends a filter or a group-by and gets back the rows or totals it asked for, computed by a database, instead of reading the whole file into the chat.

1. Sign in at app.datatomcp.com and add a CSV, a CSV link or a Google Sheet under Add data.
2. Add https://app.datatomcp.com/mcp to your client with the steps above and sign in with the same account.
3. Ask: “Use datatomcp: what were total sales per country last quarter?”

Because the URL is one per account, the same datasets show up in every client you connect. The free plan covers 3 datasets of up to 100,000 rows.

FAQ

What’s the difference between a local and a remote MCP server? A local server is a program the client starts on your machine and talks to over stdio. A remote server runs elsewhere and the client talks to it over HTTP. Remote servers work in web apps and on several machines without installing anything.

Do I need an API key for a remote MCP server? Only if the server uses header authentication. OAuth servers, like datatomcp, sign you in through the browser and the client stores the token.

Can one server be used from several clients at once? Yes. Each client signs in separately and gets its own token, which you can revoke on its own.

Is SSE still supported? It is deprecated in the MCP spec but many clients still accept it. Use HTTP when the server offers it.