Remote MCP server setup: claude mcp add, mcp.json, bridge

A remote MCP server lives at a URL. Your client connects to it over Streamable HTTP and sends a key in a header, so there is nothing to install and the same entry works on every machine. What differs between clients is only where the entry goes. This guide gives the exact form for each, checked against each client's own docs as of the updated date above, and the step most guides skip: proving the server connected.

The examples use a fetch MCP server, because that is what this site is about, with https://fetchmcp.net/mcp as the server URL and LIVE_WEB_DATA_API_KEY as the variable that holds the key. Swap in any Streamable HTTP server and its key; nothing else changes.

Which file or command each client uses

Claude Code

One command adds the server. Options go before the server name; the URL follows it.

export LIVE_WEB_DATA_API_KEY=YOUR_KEY

claude mcp add --transport http live-web-data https://fetchmcp.net/mcp \
  --header "Authorization: Bearer $LIVE_WEB_DATA_API_KEY"

Scope decides who sees the entry. The default, local, is private to you in the current project. --scope user makes it available in every project. --scope project writes it to .mcp.json at the repository root so the team shares it, and Claude Code asks each person to approve it on first use. Scope is set when you add the server, so changing it means claude mcp remove live-web-data and adding it again.

For a shared .mcp.json, keep the key out of the file. Claude Code expands environment variables in it:

{
  "mcpServers": {
    "live-web-data": {
      "type": "http",
      "url": "https://fetchmcp.net/mcp",
      "headers": { "Authorization": "Bearer ${LIVE_WEB_DATA_API_KEY}" }
    }
  }
}

Cursor

Cursor reads mcp.json from your home folder for every project, or from .cursor/mcp.json for one project. A remote server needs only url and headers:

{
  "mcpServers": {
    "live-web-data": {
      "url": "https://fetchmcp.net/mcp",
      "headers": { "Authorization": "Bearer ${env:LIVE_WEB_DATA_API_KEY}" }
    }
  }
}

Note the syntax: ${env:NAME}, not ${NAME} as in Claude Code. Cursor resolves the variable from the environment it was started in, so a variable exported only in a terminal tab is not visible to a Cursor window launched from the dock. If the header arrives as a literal ${env:...} string, start Cursor from a shell that has the variable, or update Cursor: a forum thread reported this for remote servers on one build. After editing the file, open the MCP section of Cursor's settings and check that the server shows as enabled with its tools listed.

VS Code

VS Code (Copilot agent mode) uses .vscode/mcp.json with the top-level key servers. Snippets that use mcpServers here are for other clients. The cleanest way to handle the key is an input that VS Code prompts for once and then stores securely:

{
  "inputs": [
    { "type": "promptString", "id": "live-web-data-key", "description": "Live Web Data API key", "password": true }
  ],
  "servers": {
    "live-web-data": {
      "type": "http",
      "url": "https://fetchmcp.net/mcp",
      "headers": { "Authorization": "Bearer ${input:live-web-data-key}" }
    }
  }
}

VS Code tries Streamable HTTP first and falls back to SSE for older servers. Start the server from the code lens above its entry in the file, or from the MCP servers list, and confirm its tools appear in the agent's tool picker.

Claude Desktop

Claude Desktop's config file starts servers as local commands over stdio. To reach a remote server from it, run the mcp-remote bridge, which needs Node.js:

{
  "mcpServers": {
    "live-web-data": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://fetchmcp.net/mcp",
        "--header", "Authorization:${AUTH_HEADER}",
        "--transport", "http-only"],
      "env": { "AUTH_HEADER": "Bearer YOUR_KEY" }
    }
  }
}

The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Quit and restart the app after each edit. The header is passed through env with no space after the colon on purpose: on Windows, spaces inside args are not escaped when the app runs npx, and the header breaks. Paid plans can also add a remote server under Settings, Connectors, where available. This route is correct as of this guide's update date: Claude Desktop is moving toward remote connectors that sign in with OAuth, and a server that only takes a bearer key still needs the bridge. Check Claude Desktop's own docs if your version looks different. The transport guide explains when the bridge is still needed.

Other clients

Any client that supports Streamable HTTP needs three facts: the URL, the transport, and the header Authorization: Bearer <key>. Windsurf, for example, uses its own mcp_config.json with a server URL and headers; check its docs for the exact key names in your version. A client that only launches stdio servers can use the same mcp-remote command as Claude Desktop.

Verify the connection

"Added" means saved, not connected. Check in this order:

1. Server list. claude mcp list in Claude Code should show ✓ Connected. Cursor and VS Code show a status in their MCP views.
2. Tool list. The server's tools should appear in the client. If the server connects but shows no tools, reload the window.
3. A cheap call. Ask the agent to run a tool that does no real work. On Live Web Data API's server, get_account_status returns your plan and credits and costs nothing.
4. A real call. Fetch https://example.com with a small cap. If that works, the setup is done.

If step 1 fails, the debugging runbook walks through Inspector and client logs. If the key is the problem, the authentication guide covers headers, OAuth and rotation.

Try it with a real server

Every snippet above works as written with Live Web Data API, which Teneo Labs makes and which runs a stateless Streamable HTTP server with a bearer key. Its fetch tool, get_page_contents, takes one public URL per call and returns Markdown, text or HTML, capped by max_characters. Failed requests cost no credits. Copy the current config from the MCP docs, and request a key as a business. Only Business, Enterprise and Custom sign-ups are reviewed before checkout, usually within 1 business day.