So you've heard about MCP and you want to try it. The good news is that the setup is genuinely quick. The typing takes about twenty seconds.

What eats the afternoon is that every client wants the same three facts (a name, a URL, a key) in a different shape, in a different file, under a different key name. And when you get one of them wrong, mostly nothing tells you. The server just quietly is not there.

So this guide is the copy-paste reference: one working config per client, the file it goes in, and the gotchas that break most setups. We'll use Remoet (a tech job platform with a native MCP server) as the example throughout, but swap the URL and the key and the process is identical for any remote MCP server.

Everything here was checked against the clients' own documentation in September 2026.

The one-screen version

If you only came for the field names, they are all here. Read down the last three columns and notice how little anybody agrees on.

url, serverUrl, httpUrl. Same string, three names. That is the whole difficulty of MCP setup in one row, and it is why copying a working config from one editor into another fails so confidently.

Before you start

You need two things:

1. An MCP-compatible client. Claude Code, Claude Desktop, claude.ai, Cursor, VS Code, Windsurf, Codex, Gemini CLI, ChatGPT and Cline all qualify. Not every server accepts every client, though, and ours is one of them: the clients that can reach Remoet today are Claude, Cursor, VS Code, Codex, Gemini CLI, Cline and Windsurf. The ChatGPT section below says why it is the exception.

2. Credentials for the server you want to connect. For most servers that is an API key, and for the browser-based clients it is an OAuth sign-in where you never see a key at all. For Remoet, a free key is generated for you at remoet.dev/onboarding?mode=agent, and you can manage keys later at remoet.dev/agents.

No libraries, no Docker, no build step. A config entry and a key.

Claude Code (CLI)

One line, in whatever directory you like:

claude mcp add --transport http --scope user remoet https://api.remoet.dev/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Two things about the shape of that command. Options come before the server name and the URL. And there is no --url flag, even though half the other tools on this page have one: passing it fails with error: unknown option '--url', which at least has the decency to be loud. Most of the failures in this guide are silent.

--scope user makes the server available in every project. Drop it for the current project only.

Useful follow-ups:

claude mcp list            # see all configured servers
claude mcp remove remoet   # remove one

Start a new session afterwards, then ask for something and watch the tool call fire.

Claude Desktop and claude.ai (custom connectors)

This is the zero-config path, and the one people get wrong most often, because the obvious file is the wrong file.

claude_desktop_config.json cannot add a remote server. That file is for local (stdio) servers that Claude launches as a subprocess. A remote server is added as a custom connector, once, and it then shows up in Claude Desktop and on claude.ai both.

1. Open claude.ai or Claude Desktop

2. Go to Customize > Connectors (Team and Enterprise owners: Organization settings > Connectors)

3. Click the +, then "Add custom connector"

4. Paste the OAuth URL of the server. For Remoet that is https://api.remoet.dev/mcp/oauth

5. Click Connect. Your browser opens the service's authorize page

6. Sign in and approve. Done.

Two things worth knowing. Free plans are capped at one custom connector. And the URL matters more than it looks: Remoet serves the same tools at https://api.remoet.dev/mcp for header auth and at https://api.remoet.dev/mcp/oauth for the OAuth flow. Point a connector at the first one and it will never offer you a sign-in, because that endpoint deliberately does not advertise OAuth. Nothing about the failure tells you that, so if a connector never shows you a login page, check which of the two URLs you pasted.

Local servers in claude_desktop_config.json

For completeness, since this is the file everyone searches for. On macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

On Windows:

%APPDATA%\Claude\claude_desktop_config.json

It takes command and args, not a URL:

{
  "mcpServers": {
    "some-local-server": {
      "command": "npx",
      "args": ["-y", "some-local-mcp-server"]
    }
  }
}

After editing it, fully quit and reopen Claude Desktop. On macOS, right-click the dock icon and select Quit; closing the window is not enough (this is the number one reason a correct config looks broken).

Cursor

Global config lives at ~/.cursor/mcp.json, project config at .cursor/mcp.json:

{
  "mcpServers": {
    "remoet": {
      "url": "https://api.remoet.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

type is optional for remote servers here, which after the rest of this page feels like a gift. url plus headers is the whole thing. Cursor also supports "${env:REMOET_API_KEY}" in place of a literal key, which is the better habit if the file is anywhere near a repo.

You can install and manage servers from Cursor's Customize page instead of editing the file. Each server shows its connection status there, which is the quickest way to tell a bad key from a bad config.

VS Code (GitHub Copilot)

Workspace config goes in .vscode/mcp.json. Use an input variable so the key is never written to disk in plain text:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "remoet-key",
      "description": "Remoet API key",
      "password": true
    }
  ],
  "servers": {
    "remoet": {
      "type": "http",
      "url": "https://api.remoet.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${input:remoet-key}"
      }
    }
  }
}

Look at the wrapper key. VS Code uses servers, where nearly everyone else uses mcpServers. If you paste a Cursor config in here it will parse fine as JSON and do absolutely nothing.

For a user-level server available in every workspace, run the MCP: Open User Configuration command, which opens an mcp.json in your user profile folder. MCP servers are configured in mcp.json, not in settings.json, so if you are hunting for an "mcp" key in your settings, that is why you cannot find it.

One more trap if you also use the GitHub Copilot CLI: it does not read .vscode/mcp.json. It wants its own file (.mcp.json, or .github/mcp.json) with the top-level key mcpServers and a type on every server, which is the shape everyone else uses. So the two GitHub tools on your machine disagree with each other, and copying the VS Code snippet into the CLI's file gets you an error.

Windsurf, now Devin Desktop

Cognition renamed Windsurf to Devin Desktop in June 2026. The MCP config file did not move:

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "remoet": {
      "serverUrl": "https://api.remoet.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:REMOET_API_KEY}"
      }
    }
  }
}

Two details. The URL field is serverUrl here, not url (plain url is also accepted, but every example you will find in the wild uses serverUrl, so match the examples). And ${env:VAR} interpolation works, as does ${file:/path/to/secret}, so you never need the key in the file at all. Export the variable somewhere your editor will actually see it (export REMOET_API_KEY=... in your shell profile), or the header goes out empty and the server answers 401, which reads exactly like a bad key.

You can also browse servers from the MCPs icon in the Cascade panel, or under Settings > Cascade > MCP Servers. Only Enterprise workspaces have to switch MCP on first.

Codex

One line:

codex mcp add remoet --url https://api.remoet.dev/mcp --bearer-token-env-var REMOET_API_KEY

Or by hand in ~/.codex/config.toml:

[mcp_servers.remoet]
url = "https://api.remoet.dev/mcp"
bearer_token_env_var = "REMOET_API_KEY"

bearer_token_env_var reads the key from your environment at call time, so export it first (export REMOET_API_KEY=... in your shell profile) or every call comes back unauthorized. If you need a literal header instead, http_headers = { "Authorization" = "Bearer YOUR_API_KEY" } works, and env_http_headers maps a header to an environment variable. For servers that use OAuth, codex mcp login remoet runs the browser flow.

Gemini CLI

~/.gemini/settings.json, and mind the field name: Gemini CLI calls it httpUrl.

{
  "mcpServers": {
    "remoet": {
      "httpUrl": "https://api.remoet.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

That is the entire section. Get the field name right and Gemini CLI is the least dramatic client on this page.

ChatGPT

ChatGPT connects to remote MCP servers from its own settings, with no file to edit. In the desktop app it is Settings > MCP servers > Add server, where you pick Streamable HTTP, paste the URL, and choose bearer token or OAuth. Hit Restart afterwards: the server does not appear until you do, and that is the step people miss.

On the web it is a different shape. The old Connectors and Apps surface was folded into Plugins in July 2026, and the web product no longer takes a raw MCP URL from you: you install a plugin and manage it from the Plugins tab. OpenAI's help centre still documents the older developer-mode chain, so the two sources disagree, and honestly any precise menu path you read for this (including one from us) is likely to be out of date by the time you read it. Go to Plugins and follow what is actually on the screen.

Remoet is the exception on this list. Our MCP server enforces an Origin allowlist that covers the Claude and Remoet hosts, so a connector coming from ChatGPT is refused at the door with a 403 before auth is ever considered. That is our doing, not a ChatGPT bug, and nothing you paste on their side works around it. The clients that reach Remoet today are Claude (Code, Desktop and claude.ai), Cursor, VS Code, Codex, Gemini CLI, Cline and Windsurf. Everything else in this section applies to MCP servers in general.

Cline

From the Cline panel in VS Code, open MCP Servers and paste:

{
  "mcpServers": {
    "remoet": {
      "url": "https://api.remoet.dev/mcp",
      "type": "streamableHttp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

The type is doing real work here, so do not trim it as noise. Leave it out and Cline falls back to legacy SSE, which opens a GET stream first; our server is stateless and POST-only, so that attempt gets a 405 and the connection never establishes. Same root cause as the 405 entry in troubleshooting below.

Stdio-only clients

Some older clients only speak stdio. mcp-remote bridges them to a remote server:

npx -y mcp-remote https://api.remoet.dev/mcp/oauth

That opens a browser once for the OAuth handshake and proxies everything after that. Point it at the OAuth URL rather than the bearer one: the bearer endpoint does not advertise a sign-in, so the bridge has nothing to negotiate with.

One-click installs

The newest and simplest path is not a config file at all. Cursor and VS Code both accept install deeplinks, Claude and ChatGPT both have directories where connecting is a button, and Claude Code installs a server in one command. If the server you want offers any of these, use it. Every per-client difference on this page becomes somebody else's problem, which is the correct place for it.

Troubleshooting

Nothing shows up. Restart the client properly. For desktop apps that means quitting, not closing the window; for Claude Code it means a new session.

"Unauthorized". The key is wrong, expired, or the header name is. The canonical header is Authorization: Bearer <key>. Remoet still accepts the older X-API-KEY: <key> for snippets that predate it, but do not mix the two.

Tools appear but every call errors. The connection is fine and the account is not. Check the key is live, and that you are calling the right server URL for the auth you configured.

Config file syntax errors. JSON is unforgiving. One trailing comma silently breaks the whole file. Run it through a validator before you start suspecting the server.

405 on a GET. Remoet's MCP server is stateless and POST-only: there is no session to resume and no server-to-client stream. A client that insists on opening an SSE stream first needs updating, not configuring.

What to do once connected

With Remoet connected you can ask for things like:

• Search the public job board: "Find senior Go roles in Berlin or fully remote, above 90k"

• Match companies by stack: "Which companies use Rails, React and Postgres?"

• Build your profile: "Update my summary and add my last two jobs"

• Star the companies worth hearing from: "Star that one, their stack overlaps with mine"

• Read your feed: "Anything new from my starred companies this week?"

• Keep roles on file: "Save that job and note that the salary band is below my floor"

For the full loop, read our agent job search walkthrough, or the overview of what MCP is and why it matters.

If a client here has drifted since September, or you hit a failure mode this page does not cover, come tell us in Discord. The silent failures are the ones worth collecting, and we would rather add yours than have the next person lose an afternoon to it.

Frequently Asked Questions

Can claude_desktop_config.json add a remote MCP server?

No. That file configures local servers that Claude starts as a subprocess, with command and args. A remote server over HTTPS is added as a custom connector under Customize > Connectors, and it then works in Claude Desktop and on claude.ai both.

Where is claude_desktop_config.json?

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows. Create it if it isn't there, and fully quit and reopen the app after editing.

Why does my config work in Cursor but not VS Code?

Almost always the wrapper key. VS Code uses servers; Cursor, Windsurf, Gemini CLI and Cline use mcpServers. The URL field differs too: url in Cursor, VS Code and Cline, serverUrl in Windsurf, httpUrl in Gemini CLI. Get one wrong and the server is skipped with no error.

Can I connect multiple MCP servers at the same time?

Yes. Add more entries under the same wrapper key, or run claude mcp add again with a different name. Your agent sees the tools from every connected server and can use them together in one conversation.

Do MCP servers cost money?

Depends on the server. Plenty are free. Remoet is free for job seekers, with no paid tier to upgrade to: every account gets 50 active starred companies, 25 unstars per 30 days, 5,000 MCP requests a day (an abuse ceiling, not a meter you will feel) and 10 link trees. The job board itself is public at remoet.dev/jobs with no account at all; connecting an agent to search it needs no key either, only your profile, stars and applications do.

Is my API key safe in the config file?

It's a plain-text credential on your machine, so treat it like one. Don't commit it. Better, don't put it there at all: VS Code has input variables, Cursor and Windsurf read ${env:VAR}, and Codex has bearer_token_env_var. Browser-based clients like claude.ai never touch a key in the first place.

Do I need to update the config when the server adds new tools?

No. Servers advertise their tools when a connection is established, so a new tool shows up the next time your client connects. No config change on your end.