MCP setup guide

VS Code

VS Code's Copilot harness reads MCP servers from a workspace-root `.mcp.json` or the Copilot user `mcp-config.json`. Both files use a top-level `mcpServers` object; the editor-managed `.vscode/mcp.json` format is a separate, deprecated Local-harness path.

Paths checked against the client's docs · November 2026

Surfaces

VS Code · Copilot Chat

Scope

Project or global

Project config.mcp.json
Installer agentvscode
1 / How it works

How VS Code handles MCP

VS Code's Copilot harness reads MCP servers from a workspace-root `.mcp.json` or the Copilot user `mcp-config.json`. Both files use a top-level `mcpServers` object; the editor-managed `.vscode/mcp.json` format is a separate, deprecated Local-harness path.

Project or global. Project scope keeps the server with the repository; global scope makes it available in every workspace.

Best for

Copilot users who want MCP tools beside their editor.

Installer flag-a vscode
2 / Where it goes

Where the MCP config lives

The installer writes this file for you. Use the paths below when you want to inspect, edit, or remove a server by hand.

Project
.mcp.json

Workspace-root Copilot config, offered when chat.mcp.workspaceRootConfig.enabled is on

Global
~/.copilot/mcp-config.json

Copilot user config; uses $COPILOT_HOME when set

Windows global
%USERPROFILE%\.copilot\mcp-config.json

Use the user-level file for every workspace

Project paths are relative to the workspace. Global paths are per user. On Windows, ~ means your user folder; use %USERPROFILE% in Explorer or PowerShell. A project config is shared with the team; a global config is personal.

3 / Install

Add a remote server

Start with a server in the MCP directory, or use your provider's endpoint. The examples use https://mcp.example.com/mcp so you can see the shape; replace it with the real URL.

  1. 01

    Find the endpoint

    Open a server page and copy its hosted endpoint. Do not use a local command or an npm package name for a remote server; those are different connection types.

    Open the MCP directory
  2. 02

    Run the installer

    Use the project config for a repository-specific server, or the global config for every workspace. The server name becomes example in the config.

    VS Code · project
    # Add this to VS Code MCP settings:
    {
      "mcpServers": {
        "example": {
          "type": "http",
          "url": "https://mcp.example.com/mcp"
        }
      }
    }
    VS Code · global
    # Add this to VS Code MCP settings:
    {
      "mcpServers": {
        "example": {
          "type": "http",
          "url": "https://mcp.example.com/mcp"
        }
      }
    }

    If the server page says SSE instead of HTTP, add --transport sse:

    SSE variant
    # Add this to VS Code MCP settings:
    {
      "mcpServers": {
        "example": {
          "type": "sse",
          "url": "https://mcp.example.com/mcp"
        }
      }
    }

    Prefer the native UI? Open Chat: Open Customizations, selectMCP Servers, and choose Add Server. RunMCP: Add Server for the guided flow instead. The screenshots below show each step.

    VS Code Command Palette showing MCP: List Servers selected in a clean README workspace.Open larger view
    The editor-managed MCP server picker. For the native Copilot configuration, use Chat: Open Customizations > MCP Servers instead.View full size

    The MCP server picker opens with Add Server at the top.

    If the command is missing, update VS Code and run it from a trusted workspace.

    Full screenshot
    VS Code Command Palette showing MCP: List Servers selected in a clean README workspace.
    VS Code MCP server picker with Add Server selected.Open larger view
    Choose Add Server to start a new MCP configuration instead of editing the JSON by hand.View full size

    The transport picker opens.

    If Add Server is missing, close and reopen the MCP server picker.

    Full screenshot
    VS Code MCP server picker with Add Server selected.
    VS Code Add MCP Server picker showing Command, HTTP, NPM Package, Pip Package, and Docker options.Open larger view
    For a hosted endpoint, choose HTTP (HTTP or Server-Sent Events).View full size

    The Enter Server URL prompt opens.

    For a local command, choose Command (stdio) instead of HTTP.

    Full screenshot
    VS Code Add MCP Server picker showing Command, HTTP, NPM Package, Pip Package, and Docker options.
    VS Code Enter Server URL prompt with the Cloudflare MCP endpoint filled in.Open larger view
    Paste the provider's MCP endpoint and press Enter.View full size

    The URL is accepted and the server ID prompt opens.

    Use the Streamable HTTP endpoint, not an SSE-only URL.

    Full screenshot
    VS Code Enter Server URL prompt with the Cloudflare MCP endpoint filled in.
    VS Code Enter Server ID prompt with cloudflare-code-mode entered.Open larger view
    Use a stable server ID. That ID becomes the key in the generated MCP config.View full size

    The ID is accepted and the configuration target opens.

    Use lowercase letters, numbers, and hyphens for the server ID.

    Full screenshot
    VS Code Enter Server ID prompt with cloudflare-code-mode entered.
    VS Code Add MCP Server prompt showing Global and Workspace configuration targets.Open larger view
    Choose Workspace for a repository-scoped server, or Global for every workspace.View full size

    The server entry is written to the chosen config.

    If no config appears, check the workspace for .mcp.json.

    Full screenshot
    VS Code Add MCP Server prompt showing Global and Workspace configuration targets.
  3. 03

    Authorize if the provider asks

    The first connection may open a browser for OAuth. Sign in with the provider and approve only the scopes you need. If the server uses an API key, create it in the provider's dashboard and add it through the client's auth flow or config.

    Never paste a provider token into a project config you will commit. Prefer the client's secret store or a user-level config for credentials.

  4. 04

    Reload and verify

    Run `Chat: Open Customizations`, select MCP Servers, and confirm the server is enabled. `MCP: List Servers` opens the available server controls.

    VS Code with .mcp.json open. The file defines a remote Context7 server with an HTTP endpoint.Open larger view
    The finished project config. The server entry sits under mcpServers and stays with the repository.View full size

    The server appears in Chat: Open Customizations > MCP Servers and can be started.

    If the server is missing, reload the window and confirm the JSON is valid.

    Full screenshot
    VS Code with .mcp.json open. The file defines a remote Context7 server with an HTTP endpoint.

    Then ask for a task, not a tool: “Find the open issues assigned to me” or “Summarize the latest release.” The client decides which advertised tool to call.

4 / Use

What changes in the chat

Once the server is connected, its tools appear in the client's tool list. You still talk to the agent normally; MCP is plumbing, not a different chat interface.

Read

“Find the customer notes mentioning the migration and summarize the blockers.”

Write

“Create a draft page with this outline, but do not publish it yet.”

Investigate

“Check the failed deployment and list the last three changes that touched it.”

Verify

“Which MCP tools do you have available for this task?”

If the agent ignores the server, check that the server is enabled and that its tools are approved. Some clients require a per-tool confirmation before the first call.

5 / Troubleshooting

When it does not connect

The server is missing

Confirm the file exists at the path above, the JSON or TOML is valid, and you restarted the client or opened a new session.

It connects but tools are empty

Enable the server in the client's MCP UI, approve its tools, and check that the provider has not revoked your token.

OAuth keeps reopening

Remove the server from the client, revoke the app's access in the provider's account settings, then add it again.

A project server is ignored

Some clients require you to trust the folder before loading project MCP config. Trust the repository, then start a new session.

6 / Notes

What to watch for in VS Code

  • VS Code asks you to trust and start a new MCP server before its tools appear.
  • Open Chat: Open Customizations > MCP Servers to add, edit, disable, or uninstall a server.
  • The Copilot user `mcp-config.json` is shared with GitHub Copilot CLI, not the editor-managed `.vscode/mcp.json`.
7 / Remove

Remove or reset the server

Remove the server when it is no longer needed, or reset it when a credential or connection state gets stuck.

  1. Run Chat: Open Customizations and select MCP Servers.
  2. Use the server's more actions menu to disable or uninstall it.
  3. Delete the entry from .mcp.json or ~/.copilot/mcp-config.json if it remains.

Reload the VS Code window, then add the server again if its authentication state is stale.

Sources

Official documentation

Client behavior changes. These links are the source of truth for paths, flags, and approval behavior.

Next setup guideGitHub Copilot CLI