Manage and troubleshoot MCP servers
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Manage and troubleshoot MCP servers View as Markdown Ask in VS Code Ask in VS Code Insiders Change, stop, share, or troubleshoot an existing MCP server in Visual Studio Code.
For first-time setup, see Add MCP servers . For formats and properties, see the MCP configuration reference . Use the Agent Customizations editor to edit connections, start or stop servers, change their enabled state, and view output. The editor uses the selected session's harness, workspace, and execution environment as its context. The configuration form steps below use the Copilot harness. For differences in server support and configuration, see Agent harnesses .
The Copilot runtime and the editor can connect to the same configured server independently. A control for the editor-managed connection does not necessarily affect the Copilot connection. Use the intended session's server entry, rather than assuming that a profile configuration, CodeLens action, or editor log represents the runtime server. Open the server controls In the Chat view, select the agent harness whose servers you want to manage.
Select Open Customizations in the title bar, or run Chat: Open Customizations from the Command Palette ( ⇧⌘P (Windows, Linux Ctrl+Shift+P ) ). Select MCP Servers . Select a server to edit its configuration, use its toggle to change its enabled state, or open its ellipsis ( ... ) menu for server actions. Edit an MCP server configuration To edit an existing server, open the server controls : In MCP Servers in the Agent Customizations editor, select the server from the list.
Change the server type or fields: command, arguments, and environment variables for stdio, or URL and headers for HTTP. Select Save . If a value isn't supported by the destination file, Save is unavailable and the form explains what to change. Select Discard Changes to restore saved values. Saving preserves unchanged file content and properties the form doesn't display, such as tools . Select Other Properties to open the entry in its source JSON file.
Enter arguments as a space-separated string or a JSON array of strings. With focus in the form, press Alt+F1 ( Option+F1 on macOS) to open Accessibility Help. Portable configurations support form editing. VS Code formats appear as read-only JSON, so edit their source file instead. Check the configuration file comparison for supported fields and forwarding restrictions. Legacy destinations can still be necessary for VS Code-specific capabilities.
For credentials, use environment-variable references instead of literal secrets. The workspace-root form rejects ${...} expressions; edit those references through Other Properties in the source .mcp.json . The Copilot user configuration form accepts environment-variable references. Control or remove a server In MCP Servers in the Agent Customizations editor , open the server's ellipsis ( ... ) menu and choose an available action.
Alternatively, run MCP: List Servers from the Command Palette, select the server, and choose an available action. Action When to use it Start Server Start a configured server. Stop Server End the current run. A later request can start the server again. Restart Server Restart an editor-managed connection. For Copilot runtime servers, stop the server and then start it again. Authenticate Complete authorization for a Copilot server that requires sign-in.
This action appears when authentication is required. Enable or Disable Control availability without deleting the configuration. Uninstall Remove a server you no longer need. Starting can require trust or authentication. If the server fails to start, view its output before retrying. Disabling is different from stopping. A disabled server is unavailable in the scope you choose. Use the toggle beside the server, or select an enablement action from its menu to choose a scope.
Depending on the server and harness, global, workspace, or session scope is available. The enabled state is separate from shared configuration, so disabling a server doesn't change your teammates' configuration. The configuration destination doesn't determine the enablement scope. For example, you can disable a workspace-defined server for one session, where supported, without editing its shared configuration. A global action can affect other sessions, even when you open the editor from a particular session.
For remote sessions, check the server's source and available actions in that session's context. See what customization changes affect . If a server is unavailable because its plugin is disabled, use Enable Plugin when offered. Review the plugin's other contributions before enabling it. Removal depends on the configuration source. If Uninstall isn't available for a manually configured server, remove only its entry from the source configuration, not the whole file.
If automatic discovery restores it, review its discovery source . You can also uninstall an installed server from the MCP SERVERS - INSTALLED section of the Extensions view. For GitHub-managed MCP servers, disconnect the Copilot connector instead of uninstalling a server or editing a local configuration file. Automatically start MCP servers When you submit a chat message, VS Code can start servers to discover their tools.
The chat.mcp.autostart Open in VS Code Open in VS Code Insiders setting controls this editor autostart pass: never : Don't start servers during this pass. onlyNew : Start servers that have never run. newAndOutdated (default): Start servers that have never run or whose configuration has changed. Disabled servers and servers in an error state are excluded. Important Setting chat.mcp.autostart Open in VS Code Open in VS Code Insiders to never doesn't prevent the Copilot harness from starting its own configured MCP servers independently.
To prevent a server from starting, disable it . Share and reuse configuration For compatible Copilot configurations, commit a workspace-root .mcp.json to share server definitions with your team. Review the supported configuration formats before copying entries between files. Don't commit secrets. Follow the authentication and secrets guidance for the configuration format you use. Each environment needs its own runtime, credentials, and access to external services.
Sharing a configuration doesn't install a server runtime or transport those credentials. To reuse configuration from another application, see automatic MCP server discovery . Remote workspaces and dev containers For Copilot sessions, configure native servers in .mcp.json in the session's workspace or in the Copilot user configuration on the host where the harness runs. Install stdio runtimes and provide credentials in that environment.
A local client's Copilot user file is not forwarded to a remote host. An HTTP server's URL identifies the service. Storing its configuration remotely doesn't move the service. For editor-managed compatibility, local user-profile stdio servers run locally. Use MCP: Open Remote User Configuration for the editor's remote mcp.json , not the Copilot user file. Eligible definitions can be forwarded to Copilot , where paths and dependencies must work in the harness's execution environment.
To supply an editor-managed configuration through a Dev Container, add customizations.vscode.mcp to devcontainer.json . This example uses an image with Node.js for the npx command: { "image" : "mcr.microsoft.com/devcontainers/typescript-node:latest" , "customizations" : { "vscode" : { "mcp" : { "servers" : { "playwright" : { "type" : "stdio" , "command" : "npx" , "args" : [ "-y" , "@playwright/mcp@latest" ] } } } } } } When the container is created, VS Code writes this configuration to the remote mcp.json .
This is the VS Code form
The rest of this page is on the live site.