Add a Remote MCP Server to VS Code: mcp.json and Fixes

The quickest way is the Command Palette: run MCP: Add Server, choose HTTP, paste the server's URL, and pick where to save it [1]. VS Code tries Streamable HTTP first and falls back to SSE when a server does not support it [2].

The part that has changed is where it gets saved. VS Code's documentation, last updated 7 October 2026, now lists .vscode/mcp.json and the user-profile file as deprecated destinations kept for compatibility, and tells you to prefer the portable files for new servers [1]. Most tutorials still show .vscode/mcp.json, which is why the file you are told to edit may not be the one the dialog suggests.

Everything below is checked against VS Code's MCP documentation on 12 October 2026 [1][2].

TL;DR:

• Run MCP: Add Server. It writes the entry for you [1].
• New servers go in .mcp.json at the workspace root, or ~/.copilot/mcp-config.json for every project. .vscode/mcp.json still works but is deprecated [1].
• An HTTP server is "type": "http" plus a url, with optional headers and oauth [2].
• VS Code connects from your machine. A server that works here can still be unreachable from cloud clients like ChatGPT or Claude.ai.

Pick the file

Source: [1][2].

The two formats differ in the top-level key: the portable files use mcpServers, the VS Code files use servers [2]. An example copied from one kind of file into the other needs that key changed to match.

Add the server

In VS Code's own format, which its documentation shows in every example, an HTTP server looks like this [1][2]:

{
  "servers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

The fields are type ("http" or "sse"), url, and optionally headers and oauth [2]. The url is the MCP endpoint itself, usually ending in /mcp, not the product's homepage.

VS Code's pages describe the portable format but, as of 12 October 2026, do not show a full HTTP example in it. The safest route to a correct portable entry is to let MCP: Add Server write it and choose .mcp.json or Copilot Global as the destination [1].

Keep the key out of the file

Workspace config files get committed, so do not type a token into one. VS Code's documented answer is an input variable: VS Code asks for the value the first time the server starts and stores it for you [2].

{
  "inputs": [
    {
      "type": "promptString",
      "id": "my-server-key",
      "description": "API key for my-server",
      "password": true
    }
  ],
  "servers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:my-server-key}"
      }
    }
  }
}

"password": true hides what you type [2]. That example uses the VS Code format, because that is where VS Code documents input variables. Its documentation does not yet say whether the portable files accept them, and it notes that a server needing interactive input like ${input:...} is not forwarded to Agent Host sessions [1][2]. If you need a key in a portable file, check the current docs before committing it.

Sign in to a server that needs it

When a server asks for a sign-in, VS Code opens a browser window and runs the OAuth flow on first connection [2]. Since version 1.106, VS Code uses a Client ID Metadata Document when the authorization server supports one, and Dynamic Client Registration otherwise [3].

For a server that only accepts clients registered in advance, add an oauth object with the clientId you registered [2]:

"my-server": {
  "type": "http",
  "url": "https://mcp.example.com/mcp",
  "oauth": {
    "clientId": "your-client-id"
  }
}

That case is rare. We read the authorization metadata of 169 real servers that ask for credentials, from our registry census on 9 October 2026: 162 offered Dynamic Client Registration, 33 accepted Client ID Metadata Documents, and only 6 offered neither [4]. Dynamic Client Registration explains both methods.

The trust prompt

A server in a workspace file inherits Workspace Trust: once you trust the folder, it starts without a separate prompt. A server from anywhere else shows a dialog the first time it starts and whenever its configuration changes. Decline it and the server does not start, and chat carries on without its tools [1].

When it fails to connect

For the server's own error codes, see MCP server errors and MCP server connection failed.

Check it from outside before you share it

VS Code makes its requests from your computer, so it can reach localhost, your VPN and hosts behind your firewall. ChatGPT, Claude.ai and Claude Desktop's custom connectors cannot: they call your server from their own clouds. A server that is green in VS Code tells you nothing about them.

Our MCP connection test calls your server from our network, runs the handshake and tools/list, and reports what a stranger on the internet gets back, with a dated URL you can share. The same setup in other clients is in Cursor, Claude Code, Claude Desktop and ChatGPT, and remote MCP server vs stdio covers whether your server should have a public address at all.

Sources

1. Add and manage MCP servers in VS Code, VS Code docs
2. MCP configuration reference, VS Code docs
3. October 2025 (version 1.106), VS Code release notes
4. Dynamic Client Registration, MCP Hunter glossary