How to Add a Remote MCP Server to VS Code
A practical guide to adding a remote MCP server to VS Code and GitHub Copilot: guided setup, the mcpServers format, API key and OAuth authentication, team .mcp.json setup, and troubleshooting.

Kelis Shekhaliya

TL;DR
To add a remote MCP server to VS Code, run <strong>Chat: Open Customizations</strong> > <strong>MCP Servers</strong> > <strong>Add Server</strong>, choose HTTP, and enter the URL. Save it to Copilot Global for yourself or a workspace-root <code>.mcp.json</code> for your team, using the portable <code>mcpServers</code> format. Pass API keys through <code>${VAR}</code> header references or use OAuth, and confirm with a read-only tool call.
To add a remote MCP server to VS Code, open the Command Palette, run Chat: Open Customizations, select MCP Servers, and choose Add Server. Pick HTTP, paste the server URL, give the server an ID, and save it to Global > Copilot Global for yourself or to a workspace-root .mcp.json for your team. Then complete any sign-in prompt and ask Copilot for a small task that needs one of the server's tools. If the server uses an API key, reference an environment variable in a header rather than writing the key into the file.
This guide is for SaaS founders, CTOs, and API teams who run an MCP server, or are about to, and want developers to use it from GitHub Copilot in VS Code. It covers the two configuration formats VS Code now has, the guided setup, the JSON for each authentication method, how to share a setup with a team, and what to check when a server will not connect.
Why VS Code matters for a SaaS MCP server
VS Code is where a large share of developers already work, and GitHub Copilot in VS Code can call MCP tools during a chat or agent session. When your API is available as an MCP server, a developer can ask Copilot to look up records, create objects, or check status in your product without leaving the editor or pasting data into the chat.
VS Code also has its own configuration rules. They are close to Cursor and Claude Code, but not identical, and the format changed with the move to the Copilot harness. Your setup instructions should give developers a working entry for the file VS Code actually reads. If you also support other coding tools, see how to add a remote MCP server to Cursor and how to add a remote MCP server to Claude Code.
Before you start
The server has a reachable URL. Remote servers are added by endpoint, such as
https://mcp.example.com/mcp. A server onlocalhostonly works on the machine running it.It speaks Streamable HTTP. VS Code's configuration uses
"type": "http"for Streamable HTTP and"type": "sse"for legacy SSE endpoints. Microsoft's documentation recommends HTTP when the server supports it.You know the authentication method. No authentication, a header with an API key or bearer token, or OAuth. Each one changes the entry.
Copilot is set up. AI features need to be enabled in VS Code, with Copilot selected as the session target.
The tools are tested. Confirm that discovery and a few tool calls work before you hand the setup to anyone. Our guide to testing an MCP server with MCP Inspector covers this.
Know the two configuration formats
Most confusion with MCP in VS Code comes from finding two different JSON formats in tutorials. Both exist, and they are read by different parts of VS Code.
| Portable Copilot format | Editor-managed format | |
|---|---|---|
| Files | ~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json) and workspace-root .mcp.json | .vscode/mcp.json and the user-profile mcp.json |
| Top-level key | mcpServers | servers |
| Environment variables | ${NAME} or ${NAME:-default} | ${env:NAME} |
| Input prompts for secrets | Not supported | inputs with ${input:id} |
| OAuth client ID | Flat oauthClientId field | Nested oauth.clientId object |
| Status | Recommended for new Copilot configurations | Used by the Local harness, which is deprecated and scheduled for removal in February 2027 |
For a new setup, use the portable format. VS Code can forward eligible .vscode/mcp.json definitions into Copilot sessions, but entries that depend on ${input:...} or ${command:...} variables are not forwarded. If your current instructions rely on input prompts, plan a move to environment variables or OAuth.
Add the server with guided setup
Open the Command Palette (
Ctrl+Shift+P, orCmd+Shift+Pon macOS) and run Chat: Open Customizations. Select MCP Servers, then Add Server. Running MCP: Add Server starts the same flow.Choose HTTP (HTTP or Server-Sent Events) and enter the endpoint, for example
https://mcp.example.com/mcp.Enter a unique server ID. Microsoft suggests descriptive names without spaces or special characters, in camelCase for several words, such as
myApi.Choose a destination. Global > Copilot Global writes your personal configuration. A workspace-root
.mcp.jsonis offered when the experimentalchat.mcp.workspaceRootConfig.enabledsetting is on.Review any trust request, then complete the sign-in if the server asks for one.
Copilot Global is shared across your workspaces and with compatible Copilot experiences on the same machine, including Copilot CLI. It does not sync to your other machines.
Write the JSON yourself
You can skip the form and edit the file directly. A remote server with no authentication looks like this:
{
"mcpServers": {
"myApi": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"tools": ["*"]
}
}
}The tools field lists which of the server's tools are available. ["*"] makes all of them available; listing specific names narrows the set. It does not bypass tool approvals.
API key or bearer token
Put the credential in a header and reference an environment variable instead of the literal value:
{
"mcpServers": {
"myApi": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${MY_API_TOKEN}"
},
"tools": ["*"]
}
}
}Use the braced ${NAME} form; VS Code's MCP client treats a bare $NAME as literal text. Set the variable in the environment of the machine that connects to the server. The header name depends on your server: some expect Authorization, others a custom header such as X-API-Key. Microsoft's guidance is direct: do not commit tokens or populated authentication headers, and do not treat a personal configuration file as a secret store.
OAuth
For a server that supports OAuth, the URL is usually enough. VS Code coordinates the sign-in for Copilot sessions: complete the authorization when prompted, or use Authenticate in the server's actions. If the server requires a pre-registered OAuth client, add the flat oauthClientId field to the entry. For background on choosing between keys and OAuth for your own server, see our guide to MCP API authentication.
Share the setup with your team
A workspace-root .mcp.json can be committed to the repository, so everyone who opens the project gets the same server definition. Keep it free of secrets: commit the URL and header names with ${VAR} references, and document which variables each developer needs to set. Each person still completes their own OAuth sign-in or supplies their own key.
Two details matter for teams on remote setups. In remote and Dev Container sessions, the personal configuration refers to the home directory where the Copilot harness runs, and a local ~/.copilot/mcp-config.json is not forwarded to that host. Configure the server in the environment where the session runs. Administrators can also control which MCP servers are allowed in VS Code with the chat.mcp.access setting, so check organization policy if a server never appears.
Verify the connection
Adding a configuration does not prove Copilot can use the server. Ask for a low-impact task that needs one of its tools, and name the server to make the test clear:
Use the myApi MCP tools to list my three most recent projects. Do not change anything.Expand the tool call in the conversation and confirm that it went to your server and returned real data. A plausible answer with no tool call does not verify the connection. Start with a read-only tool before anyone tries a write.
Troubleshooting
The server does not appear or cannot start
Check that the entry is in a file Copilot reads. A server added to .vscode/mcp.json or through code --add-mcp lands in the editor-managed format, not the portable Copilot files. Confirm the top-level key matches the file (mcpServers or servers), that the entry has a type, and look at the server output for errors.
Sign-in or the connection fails
Check the URL path (many servers serve MCP at /mcp, not the root), the authentication method the server expects, and your organization's access restrictions. If you use a header, confirm the environment variable is set where VS Code connects from.
A server that worked before no longer shows up in Copilot
Look for ${input:...} variables in its .vscode/mcp.json entry. Those servers are not forwarded into Copilot harness sessions. Move the credential to an environment-variable reference in the portable format, or use OAuth if the server supports it.
The server runs but its tools are not used
Copilot selects tools from their names and descriptions. Check that the tools are enabled for the session, then look at the tools themselves: clear names, precise descriptions, and a focused set make it easier for the model to pick the right one.
Adding a 0mcp server to VS Code
If your MCP server is hosted on 0mcp, you do not need to write the entry from scratch. Publish a server version, open Setup, and select VS Code. 0mcp generates the server entry; merge it into .vscode/mcp.json alongside any servers already there, start the server from MCP: List Servers, and enter the upstream API credential when VS Code asks for it, so the value is not written into the file. The 0mcp VS Code setup guide has the details. If your team works in the portable format, keep the same server URL and supply the credential through an environment-variable header as shown above.
Final checklist
The server URL is public and serves Streamable HTTP.
New entries use the portable
mcpServersformat with"type": "http".Personal servers are in Copilot Global; shared ones are in a workspace-root
.mcp.json.Secrets come from
${VAR}references or OAuth, never from committed files.No entry you rely on in Copilot depends on
${input:...}prompts.A read-only tool call shows up in the conversation and returns real data.
FAQ
01How do I add a remote MCP server to VS Code?+-
Run <strong>Chat: Open Customizations</strong>, select <strong>MCP Servers</strong>, choose <strong>Add Server</strong>, pick HTTP, and enter the server URL and an ID. Save it to Copilot Global for yourself or a workspace-root <code>.mcp.json</code> for your team, then sign in if prompted and test a tool call.
02Should I use .vscode/mcp.json or .mcp.json?+-
For new Copilot configurations, Microsoft recommends the portable format: <code>~/.copilot/mcp-config.json</code> for personal servers and a workspace-root <code>.mcp.json</code> for shared ones, both with a top-level <code>mcpServers</code> object. <code>.vscode/mcp.json</code> uses the editor-managed <code>servers</code> format of the deprecated Local harness, though eligible entries can still be forwarded.
03How do I pass an API key to an MCP server in VS Code?+-
Add a <code>headers</code> object to the server entry and reference an environment variable, for example <code>"Authorization": "Bearer ${MY_API_TOKEN}"</code>. Use the braced form and set the variable on the machine that connects to the server. Do not commit literal keys.
04Does VS Code support OAuth for remote MCP servers?+-
Yes. VS Code coordinates OAuth sign-in for Copilot sessions: complete the authorization when prompted or use Authenticate in the server's actions. If the server needs a pre-registered OAuth client, add <code>oauthClientId</code> to the portable entry.
05Why doesn't my MCP server show up in Copilot after it worked before?+-
Servers in <code>.vscode/mcp.json</code> that use <code>${input:...}</code> or <code>${command:...}</code> variables are not forwarded into Copilot harness sessions. Move the credential to an environment-variable reference in the portable format, or use OAuth.
06Can my whole team share one MCP configuration in VS Code?+-
Yes. Commit a workspace-root <code>.mcp.json</code> with the server URL and <code>${VAR}</code> references for any credentials. Each developer sets their own variables or completes their own OAuth sign-in.