MCP configuration reference
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. MCP configuration reference View as Markdown Ask in VS Code Ask in VS Code Insiders Configure MCP servers for the Copilot harness with the portable mcpServers format.
This reference covers configuration locations, fields, authentication, and relevant controls. Connect a server to Copilot: choose a configuration destination , then use the portable examples and fields . Reuse an existing editor configuration: check forwarding and migration . Maintain a deprecated Local configuration: use the separate Local compatibility reference . For a complete first-time walkthrough, see Add MCP servers .
To operate an existing server, see Manage and troubleshoot MCP servers . Configuration compatibility is separate from protocol support. For tools, prompts, resources, roots, sampling, elicitation, and MCP Apps, see MCP support and limitations . Configure MCP for Copilot Use the Agent Customizations editor to add a server to the intended Copilot session: Select the Copilot harness in a chat session, then run Chat: Open Customizations and select MCP Servers .
Select Add Server , provide the publisher's command or endpoint, and choose a destination below. For personal configuration, select Global > Copilot Global . Complete any authentication prompts and verify a tool call . Adding a configuration alone doesn't confirm that the session can use the server. Configuration file Choose a native Copilot destination. Both files use a top-level mcpServers object, and the harness reads them directly.
Your goal Configuration file Guided setup destination Use a server across your workspaces $COPILOT_HOME/mcp-config.json , or ~/.copilot/mcp-config.json when COPILOT_HOME is unset Global > Copilot Global Share server definitions with your team .mcp.json at the workspace root Workspace-root .mcp.json , offered when the Experimental chat.mcp.workspaceRootConfig.enabled Open in VS Code Open in VS Code Insiders setting is on As an alternative to guided setup, edit the native file using the portable configuration examples .
Existing workspace-root .mcp.json files remain available when the guided-setup setting is off. Important For new Copilot configurations, use these native destinations, not .vscode/mcp.json or profile mcp.json . Those files use the deprecated Local harness's The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . editor-managed servers format.
Eligible existing definitions can be forwarded , but the harness doesn't read those files directly. Plugin-provided servers travel with their plugin. Installing a plugin is different from copying its server definitions into a personal or workspace configuration. For remote and Dev Container sessions, native user configuration refers to the home directory where the harness runs. The connected client's $COPILOT_HOME/mcp-config.json (or ~/.copilot/mcp-config.json ) isn't forwarded to another host or harness.
Configure the server in the execution environment or use an eligible forwarded configuration instead. See remote session customization sources . For other providers, use the provider's MCP configuration documentation. Their configuration locations and schemas can differ. The guided setup and configuration form support a subset of the native file's options. Both native destinations have a configuration form in the Agent Customizations editor: Destination Transports offered in the form Working-directory field Copilot user mcp-config.json stdio, HTTP, and legacy SSE Yes Workspace-root .mcp.json stdio and HTTP No The configuration form preserves properties that it doesn't display.
Select Other Properties in the form to open the complete server entry in JSON. Portable configuration Use a top-level mcpServers object in workspace-root .mcp.json or Copilot user mcp-config.json . This example configures one local Playwright server: { "mcpServers" : { "playwright" : { "type" : "stdio" , "command" : "npx" , "args" : [ "-y" , "@playwright/mcp@latest" ], "tools" : [ "*" ] } } } Install the publisher's runtime prerequisites before starting the server.
The Playwright setup requirements include Node.js 18 or newer. For an HTTP server, replace the server entry with the publisher's endpoint: { "mcpServers" : { "context7" : { "type" : "http" , "url" : "https://mcp.context7.com/mcp" , "tools" : [ "*" ] } } } Follow the Context7 setup instructions for authentication and service limits. An endpoint alone doesn't grant access to a service. These are common fields in a portable server entry: Field Applies to Purpose type All servers stdio for a command, http for Streamable HTTP, or sse for a legacy SSE endpoint.
Prefer HTTP when the server supports it. command , args stdio Executable and its arguments. Install the runtime where the harness runs. env stdio Environment-variable values or references. Use strings for values. cwd stdio Working directory. The Copilot user configuration form supports this field; the workspace-root form does not. url , headers HTTP and SSE Endpoint and optional request headers. Don't store literal credentials in shared files. tools All servers Tool names to make available. ["*"] makes all server tools available; use specific names to limit the selection.
This doesn't bypass tool approvals. oauthClientId HTTP and SSE Client ID for a server that requires a pre-registered OAuth client. This is a flat field, not the editor format's nested oauth object. For additional runtime-specific options, see the Copilot CLI MCP configuration guidance . Don't copy editor-only fields such as inputs , envFile , dev , or sandboxEnabled into a portable file. Environment-variable references Portable configurations support environment variables independently of VS Code input prompts.
Use ${NAME} to reference a value, or ${NAME:-default} for a non-secret default. Stdio servers can use references in command , args , and env values. HTTP servers can use them in header values. Provide variables in the environment of the host that runs or connects to the server. For remote sessions, that is the remote host or container. Use the braced ${NAME} form for compatibility across the Copilot runtime and the VS Code MCP client, which treats bare $NAME as literal text.
You can edit environment variables and HTTP headers in the Copilot user MCP configuration form . Enter references rather than literal credentials. The workspace-root form rejects ${...} expressions, so use Other Properties to edit references in the source .mcp.json instead. A form restriction does not mean that the Copilot runtime cannot read the reference. Support for environment variables does not include envFile , input prompting, or a bridge to VS Code SecretStorage .
For a worked example, see Replace input prompts with environment variables . Authentication and secrets Authentication grants access to an external service. It is separate from trusting a server to start and approving individual tool calls. Server requirement Copilot guidance Browser sign-in or OAuth Follow the publisher's instructions and complete authorization when prompted. Use Authenticate in the session's server actions when offered.
The editor coordinates authentication for Copilot sessions in VS Code; don't assume another client shares its saved credentials. A pre-registered OAuth client Use supported flat Copilot fields such as oauthClientId , not the editor format's nested oauth object. See the Copilot CLI guidance . An API key or fixed token Use environment-variable references if they meet your requirements. Provide credentials in the environment of the host that runs or connects to the server.
VS Code input prompts or an environment fil
The rest of this page is on the live site.