Remote MCP Server in Cursor, Claude Code, VS Code und Claude Desktop einbinden

Posted on Oct 23 • Originally published at fabwaseem.com

A remote MCP server is a Model Context Protocol server you reach over HTTPS instead of starting it on your own machine. You add it with a URL, not a command. Every major AI coding client supports this now, but each one wants the URL in a slightly different shape. Cursor takes a bare url, Claude Code wants "type": "http", VS Code has two file formats, and Claude Desktop doesn't read a URL from its config file at all.

This guide gives you the working setup for each client, using a real public server: Benchline, my open-source developer tools site, which serves its tools over MCP at https://benchline.fabwaseem.com/mcp with no API key and no session. I checked every config block against the official docs on October 23, 2026, ran the Claude Code commands for real, called a tool through the official TypeScript SDK and through mcp-remote, and measured what the server costs in latency and in tokens. All numbers below come from those runs.

Before you blame the client, test the server with curl or the MCP Inspector. A remote server that answers tools/list will work in all four.

MCP has two standard transports. With stdio, the client starts the server as a child process ( npx some-server ) and talks to it through stdin and stdout. The server runs on your machine, with your files and your environment variables. With Streamable HTTP, the server is a web endpoint. The client POSTs JSON-RPC messages to one URL and reads the answer as JSON or as a Server-Sent Events stream. The transport spec defines both. The older HTTP+SSE transport is deprecated, and Claude Code's docs say to use HTTP where you can.

A remote server is just the second kind, hosted somewhere public. That has real advantages. You install nothing, the publisher ships fixes without asking you to update, and the same URL works in every client. It also means the server never sees your disk, which is a security win for tools that don't need it.

Benchline's endpoint is stateless: each POST stands alone, it returns no Mcp-Session-Id, and it answers with plain JSON. I explain how that server is built in Building Benchline: a stateless MCP server, and what the newer stateless spec changes in Stateless MCP servers and the 2026-07-28 spec. For this guide, all you need is the URL.

A Streamable HTTP server must get both application/json and text/event-stream in the Accept header. This call lists the tools:

curl -sS -X POST https://benchline.fabwaseem.com/mcp \ -H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' Enter fullscreen mode Exit fullscreen mode And this one calls a tool:

curl -sS -X POST https://benchline.fabwaseem.com/mcp \ -H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"format_json","arguments":{"json":"{\"a\":1}"}}}' Enter fullscreen mode Exit fullscreen mode Benchline accepts tools/list and tools/call without an initialize first, because it builds a fresh server for every request. A sessionful server would want initialize first and an Mcp-Session-Id header after that. When I sent initialize with protocol version 2025-06-18, the server answered with serverInfo benchline, the tools capability and no session header.

If you prefer a real client to raw JSON-RPC, the MCP Inspector has a CLI mode. Version 2.12.0 needs Node.js 22.19 or newer:

npx @modelcontextprotocol/inspector --cli \ --transport http --server-url https://benchline.fabwaseem.com/mcp \ --method tools/call --tool-name format_json --tool-arg 'json="{\"a\":1}"' Enter fullscreen mode Exit fullscreen mode One gotcha I hit: --tool-arg parses the value as JSON. My first try, json={"a":1}, sent an object, and the tool rejected it with -32602 Input validation error: expected string, received object. Wrapping the value in quotes makes it a JSON string.

Cursor reads ~/.cursor/mcp.json for servers you want in every project, and.cursor/mcp.json in a project for that project only. A remote server needs only a url:

{ "mcpServers": { "benchline": { "url": "https://benchline.fabwaseem.com/mcp" } } } Enter fullscreen mode Exit fullscreen mode For a server that needs a token, add headers and read the value from your environment with Cursor's ${env:NAME} interpolation, so the secret never lands in the file:

{ "mcpServers": { "my-api": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" } } } } Enter fullscreen mode Exit fullscreen mode Servers that use OAuth need no header. Cursor runs the sign-in itself, using PKCE and the server's protected resource metadata. If a server doesn't show up, open the Output panel and pick MCP Logs. Source: Cursor MCP docs.

Claude Code has a one-line command for remote servers:

claude mcp add --transport http benchline https://benchline.fabwaseem.com/mcp claude mcp list Enter fullscreen mode Exit fullscreen mode On Claude Code 2.1.309 this printed Added HTTP MCP server benchline with URL: https://benchline.fabwaseem.com/mcp to local config, and claude mcp list showed benchline: https://benchline.fabwaseem.com/mcp (HTTP) - ✔ Connected. The default scope is local: the entry is saved in ~/.claude.json under the current project. Add --scope user to use it in every project, or --scope project to write it to.mcp.json and commit it for your team. For a token, pass --header "Authorization: Bearer …". For OAuth servers, run /mcp inside a session or claude mcp login <name>.

{ "mcpServers": { "benchline": { "type": "http", "url": "https://benchline.fabwaseem.com/mcp" } } } Enter fullscreen mode Exit fullscreen mode Don't paste a Cursor block into.mcp.json. Claude Code reads an entry without type as a stdio server. When I tried the Cursor-style block above, claude mcp list printed Skipped — invalid MCP server config for "benchline": command: expected string, received undefined, and the server was not loaded. Adding "type": "http" fixes it, and "streamable-http" works as an alias. Source: Claude Code MCP docs.

VS Code now reads two formats, and it matters which file you edit.

The VS Code format lives in.vscode/mcp.json in your workspace, or in your user profile. It uses a top-level servers object, and type is required:

{ "servers": { "benchline": { "type": "http", "url": "https://benchline.fabwaseem.com/mcp" } } } Enter fullscreen mode Exit fullscreen mode The portable format lives in.mcp.json at the workspace root, or in ~/.copilot/mcp-config.json for your user. It uses mcpServers, the same shape as Claude Code's file, so one committed.mcp.json can serve both tools:

{ "mcpServers": { "benchline": { "type": "http", "url": "https://benchline.fabwaseem.com/mcp" } } } Enter fullscreen mode Exit fullscreen mode The guided MCP: Add Server command now suggests the Copilot Global file first and labels.vscode/mcp.json as deprecated, though VS Code still reads it. The two formats handle secrets differently..vscode/mcp.json supports ${input:…} prompts and ${env:NAME}, while portable files use ${NAME} and no input prompts. VS Code first tries Streamable HTTP and falls back to SSE. Source: VS Code MCP configuration reference.

This is where most copy-paste setups break. claude_desktop_config.json is for local stdio servers. The supported way to add a remote server is a custom connector:

Custom connectors work on Free (one connector), Pro, Max, Team and Enterprise plans. On Team and Enterprise, an Owner adds the connector first. One detail matters a lot: Claude connects to a custom connector from Anthropic's cloud, not from your computer. The server has to be reachable from the public internet. A server on localhost, behind a VPN or on a company network won't connect, even if curl works on your laptop. Source: Claude Help Center.

For those servers, bridge the URL to stdio with mcp-remote in claude_desktop_config.json (on macOS in ~/Library/Application Support/Claude/, on Windows in %APPDATA%\Claude\ ):

{ "mcpServers": { "benchline": { "command": "npx", "args": [ "-y", "mcp-remote", "https://benchline.fabwaseem.com/mcp" ] } } } Enter fullscreen mode Exit fullscreen mode Claude Desktop starts mcp-remote as a local process, and mcp-remote speaks Streamable HTTP to the server from your own network. I tested this by starting mcp-remote 0.15.2 from the official TypeScript SDK's stdio client, the way Claude Desktop would. The format_json call came back valid. The first start took 11.2 s, including npx fetching the package, and the call itself took 970 ms. For a token, use --header and keep the value in env, or --header-file so the secret stays out of the process list.

To check a server from code, or to use one in your own agent, the official SDK client takes about ten lines:

import { Client } from " @modelcontextprotocol/sdk/client/index.js "; import { StreamableHTTPClientTransport } from " @modelcontextprotocol/sdk/client/streamableHttp.js "; const client = new Client ({ name: " remote-mcp-check ", version: " 1.0.0 " }); await client. connect ( new StreamableHTTPClientTransport ( new URL ( " https://benchline.fabwaseem.com/mcp " )), ); const { tools } = await client. listTools (); const result = await client. callTool ({ name: " format_json ", arguments: { json: ' {"b":2,"a":[1,2]} ' }, }); console. log ( result. structuredContent ); // { output: '{\n "b": 2, …', valid: true, errors: [] } await client. close (); Enter fullscreen mode Exit fullscreen mode With @modelcontextprotocol/sdk 1.32.1, the client negotiated protocol 2025-11-25, got no session id, and the call returned structuredContent with valid: true. Twenty calls on that connected client took a median of 375 ms and a p95 of 419 ms.

The v2 client, @modelcontextprotocol/client 2.3.1, with versionNegotiation: { mode: "auto" } also connected and fell back to 2025-11-25, because Benchline's server doesn't speak 2026-07-28 yet. A direct 2026-07-28 request got Unsupported protocol version, and the list of versions the server does accept. Clients that negotiate handle this for you. Claude Code's v2 runtime, for example, asks each server which revision it supports and uses the newer one only where the server has it.

Speed is rarely the problem with MCP. Tokens are. Each tool's name, description and JSON Schema can end up in the model's context, and that's paid on every turn. So I measured Benchline's tools/list:

These are approximations. o200k_base is OpenAI's tokenizer, Claude and other models count differently, and each client decides which fields it forwards. Still, the order of magnitude holds. For comparison, the MCP server behind this site came to 5,949 tokens in my MCP vs API benchmark. Some clients soften the cost. Claude Code uses tool search by default, so Claude can look up tools when it needs them. VS Code lets you choose which tools a session can use, and Cursor lets you toggle whole servers off. Turn off what you aren't using.

I measured with curl from my build box, which reaches the internet through an egress proxy, so the absolute numbers include that path. Yours will differ. The pattern is the useful part:

On a fresh connection, the TCP and TLS setup alone took a median of 928 ms before the first byte of the request went out. On a reused connection, tools/list sent its first byte after a median of 395 ms, and most of the remaining time went into downloading the uncompressed 138 KB body. Real clients keep connections open and fetch the tool list once per session, so you pay the slow path roughly once. Two practical points follow. A server with a large tool list should support compression. And MCP_TIMEOUT in Claude Code, or your client's equivalent, should allow a few seconds for the first connect.

Every error below is one I triggered against the live server or found in the client docs:

A remote server can't read your files, but it can still influence your agent. Before adding one:

For the server side, including the OAuth SDK flaws I reproduced this month, read MCP security in 2026. If you want to build a remote server of your own, How to build an MCP server in Next.js covers the route handler, bearer auth and Origin checks.

All tests ran on October 23, 2026, from my Linux build box against the live https://benchline.fabwaseem.com/mcp:

A Model Context Protocol server you reach over HTTPS with the Streamable HTTP transport, instead of a local process your client starts over stdio. You add it with a URL, nothing is installed on your machine, and the same URL works in Cursor, Claude Code, VS Code and Claude Desktop.

How do I add a remote MCP server to Cursor?

Add an entry with only a url under mcpServers in ~/.cursor/mcp.json for all projects, or.cursor/mcp.json for one project, for example "benchline": { "url": " https://benchline.fabwaseem.com/mcp " }. Add headers with ${env:NAME} for token auth. Cursor runs OAuth itself for servers that need it.

What is the claude mcp add command for an HTTP server?

claude mcp add --transport http, for example claude mcp add --transport http benchline https://benchline.fabwaseem.com/mcp. It saves to local scope by default. Add --scope user for every project or --scope project to write.mcp.json, and --header for a bearer token. Check it with claude mcp list.

Why does Claude Code skip my MCP server from.mcp.json?

An entry with a url but no type is read as a stdio server and skipped. In my test Claude Code 2.1.309 reported command: expected string, received undefined. Add "type": "http" (or the alias "streamable-http") next to the url.

Can I put a remote URL in claude_desktop_config.json?

No. That file is for local stdio servers. Add remote servers in Claude Desktop under Customize > Connectors > Add custom connector. For a server that Anthropic's cloud cannot reach, run npx -y mcp-remote as a stdio command in claude_desktop_config.json.

Why does my custom connector fail in Claude when curl works?

Claude connects to custom connectors from Anthropic's cloud, not from your computer. A server on localhost, a VPN or a private network is unreachable from there. Host it publicly, allowlist Anthropic's IP ranges, or bridge it with mcp-remote, which connects from your own network.

How many tokens does an MCP server add to the context?

It depends on its tool schemas. Benchline's tool names, descriptions and input schemas came to 17,517 tokens with the o200k_base tokenizer, and the whole tools/list response to 34,307. The MCP server behind fabwaseem.com is 5,949 tokens. Turn off servers and tools you don't need.

How do I test a remote MCP server without an AI client?

POST a tools/list JSON-RPC request with curl, sending content-type: application/json and accept: application/json, text/event-stream, or run npx @modelcontextprotocol/inspector --cli --transport http --server-url --method tools/list. A missing Accept type returns HTTP 406.

Originally published on fabwaseem.com, where I write about MCP, AI automation, Node.js and Next.js.

Expand Sherotree Sherotree Sherotree Follow Being a developer means being a student for life Email tangweikun123@gmail.com Joined Jun 7, 2022 • Oct 23 Dropdown menu Copy link Hide The "curl tools/list before you blame the client" check is the bit I will steal. I have wasted more than one afternoon chasing a Cursor mcp.json typo when the server was just not answering. Also did not clock that Cursor wants a bare url while Claude Code needs "type": "http" — that mismatch alone explains a few of my earlier silent fails.

Like comment: 1 like Like Comment button Reply Collapse Expand Waseem Anjum Waseem Anjum Waseem Anjum Follow Full Stack & AI Automation Engineer. I build AI agents, MCP servers and SaaS with Next.js, NestJS, Python & TypeScript. Lahore, PK · fabwaseem.com Location Lahore, Pakistan Joined Jan 12, 2024 • Oct 23 Dropdown menu Copy link Hide Glad that one helped. That mismatch bit me too while testing: I pasted the Cursor-style block into.mcp.json and Claude Code just skipped the server, with command: expected string, received undefined in claude mcp list. Without "type": "http" it assumes a stdio server and goes looking for a command. Running claude mcp list after editing the file is a quick way to catch it, because Cursor and Claude Code both tend to fail quietly otherwise.