MCP configuration reference

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:

1. Select the Copilot harness in a chat session, then run Chat: Open Customizations and select MCP Servers.

2. Select Add Server, provide the publisher's command or endpoint, and choose a destination below. For personal configuration, select Global > Copilot Global.

3. 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.

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.

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:

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:

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.

Do not commit tokens, passwords, or populated authentication headers. A personal configuration file is not a secret store.

The Copilot harness has no built-in MCP configuration option to forward a ${input:...} secret or read an existing VS Code SecretStorage value into an HTTP authentication header. OAuth can be an alternative when the server supports it, but it does not substitute a prompted API key. If your integration requires a static bearer token without environment variables or credentials in files, see the migration FAQ.

Server naming conventions

Use a descriptive, unique name for each server you use together, such as github or database. Avoid whitespace and special characters. For multi-word names, use camelCase, such as uiTesting or githubIntegration.

Commands

Use these commands for Copilot setup and management from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

Commands that open profile mcp.json or .vscode/mcp.json, and code --add-mcp, target editor-managed configuration, not the portable Copilot files.

Settings

These settings are relevant to Copilot setup or its connected editor. They don't replace the server entries in the native configuration file.

Copilot reads its native configuration independently of the editor's discovery setting. The editor's autostart and sampling-model settings also don't control the native runtime. Use server enablement to prevent a server from starting, and review the Copilot sampling approval flow for model requests.

For the full settings list, see the AI Settings Reference. Settings for the deprecated Local path are listed under editor-managed settings.

Editor forwarding to Copilot

Editor forwarding reuses an eligible server definition in a Copilot session. It does not move the original file or turn an editor-managed server connection into the runtime's connection. Prefer native configuration for integrations that must work without the editor.

• Workspace .vscode/mcp.json, profile configurations, and eligible extension-provided definitions can be forwarded. Extension discovery and definition resolution require the contributing extension and editor.
• Configurations requiring ${input:...} or ${command:...} are rejected before variable resolution. Resolving or caching the value in Local first does not make the configuration eligible.
• Editor development mode, per-server sandbox rules, and envFile behavior do not transfer. Review authentication options and working-directory paths in the destination environment.
• Copilot user configuration is read on the host where the harness runs, not forwarded from a different host. Plugin servers are delivered with their plugin rather than duplicated as standalone definitions.

Forwarding is not automatic migration. Migration writes native files and can remove successfully migrated source entries; forwarding leaves the source configuration in place.

When reusing an existing configuration, check these differences:

Editor-managed configuration for Local harness compatibility

The Local harness is deprecated. Use this section only to maintain an existing editor-managed configuration, not to set up a new native Copilot server.

The following schemas and examples apply to the servers format in workspace .vscode/mcp.json or user-profile mcp.json. These files appear as read-only JSON in the Agent Customizations editor; edit their source file instead. A server using this format might be eligible for forwarding, but editor-specific behavior does not automatically carry over.

Configuration structure

The following structure applies to the VS Code format. The portable Copilot format uses a separate schema with a top-level mcpServers object.

The configuration file has three main sections:

• "servers": {}: an object that maps server names to their configurations. Each key is the server name, and the value is the server configuration object. Depending on the server type, different fields are required.

• "inputs": []: an optional array of input variable definitions for sensitive information like API keys.

• "sandbox": {}: an optional object that defines file system and network access rules for sandboxed servers. See Sandbox configuration. Only applies on macOS and Linux.

You can use predefined variables in the server configuration, for example to refer to the workspace folder (${workspaceFolder}).

Standard I/O (stdio) servers

Use this editor-managed configuration for servers that communicate through standard input and output streams.

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Sandbox configuration

Editor-managed sandboxing restricts file system and network access for stdio MCP servers on macOS and Linux. It does not configure the Copilot harness sandbox and its chat.agent.sandbox.mcpServers Open in VS Code Open in VS Code Insiders setting.

To enable sandboxing for a server, set "sandboxEnabled": true in its configuration. Add a sandbox object to the server to define its file system and network permissions. You can also add a top-level sandbox object as a sibling of servers and inputs to define deny rules that apply to all sandboxed servers in the file.

Allow rules are supported only in a server's sandbox object. Top-level allowWrite and allowedDomains rules are ignored.

The server-level and top-level sandbox objects support the following properties:

You can use predefined variables, such as ${workspaceFolder}, in file system path values.

{
  "servers": {
    "myServer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "sandboxEnabled": true,
      "sandbox": {
        "filesystem": {
          "allowWrite": ["${workspaceFolder}"]
        },
        "network": {
          "allowedDomains": ["api.example.com", "*.cdn.example.com"]
        }
      }
    }
  },
  "sandbox": {
    "filesystem": {
      "denyRead": ["${userHome}/.ssh"]
    }
  }
}

HTTP and Server-Sent Events (SSE) servers

Use this editor-managed configuration for servers that communicate over HTTP. The editor's MCP client first tries the Streamable HTTP transport and falls back to SSE if HTTP is not supported.

In addition to servers available over the network, VS Code can connect to MCP servers listening for HTTP traffic on Unix sockets or Windows named pipes by specifying the socket or pipe path in the form unix:///path/to/server.sock or pipe:///pipe/named-pipe on Windows. You can specify subpaths by using a URL fragment, such as unix:///tmp/server.sock#/mcp/subpath.

The oauth object supports the following properties:

{
  "servers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

{
  "servers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "clientId": "example-client-id"
      }
    }
  }
}

Input variables for sensitive data

Input variables in the VS Code format let you define placeholders for values such as API keys or passwords. They aren't supported in portable configuration files, and servers that require them aren't forwarded to Copilot harness sessions.

Forwarding rejects input and command variables before resolving them. Entering or caching the secret in a Local session 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. first does not make the server available to Copilot. Keep the original configuration until a supported authentication method works in the destination harness.

When you reference an input variable using ${input:variable-id}, VS Code prompts you for the value when the server starts for the first time. The value is then securely stored for subsequent use. Learn more about input variables in VS Code.

Each input variable has a type that determines how VS Code prompts for the value. The following input types are supported:

• promptString: opens an input box to ask the user for a free-text value.
• pickString: shows a list of options for the user to choose from.
• command: runs a command and uses its result as the input value.

Common properties:

promptString properties:

pickString properties:

command properties:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "perplexity-key",
      "description": "Perplexity API Key",
      "password": true
    }
  ],
  "servers": {
    "perplexity": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "server-perplexity-ask"],
      "env": {
        "PERPLEXITY_API_KEY": "${input:perplexity-key}"
      }
    }
  }
}

Development mode

For editor-managed servers, add a dev key to the server configuration to use development mode. This does not configure a server started independently by the Copilot runtime. The object has two properties:

• watch: A glob pattern, or an array of glob patterns, to watch for file changes that restart the MCP server. Available for all server types.
• debug: Enables you to set up a debugger with the MCP server. Currently, VS Code supports debugging Node.js and Python MCP servers. Available for stdio servers only.

Learn more about MCP development mode in the MCP integration reference.

Automatic MCP server discovery

The editor can automatically detect and reuse MCP server configurations from supported applications. Use chat.mcp.discovery.enabled Open in VS Code Open in VS Code Insiders to select these discovery sources. This is separate from native Copilot discovery and plugin-provided servers.

GitHub Copilot CLI discovery is on by default. All other discovery sources are off by default. In a remote window, VS Code resolves configuration locations and environment variables in the remote environment.

For GitHub Copilot CLI, setting COPILOT_HOME replaces the default ~/.copilot location. VS Code does not check both locations.

Editor-managed commands

These commands operate on editor-managed configuration or connections. They aren't the native Copilot configuration workflow.

Command-line installation

Use code --add-mcp with a JSON object containing a unique name and the server configuration. The command adds a server to the VS Code user-profile configuration.

For example, from a Bash shell:

code --add-mcp '{"name":"playwright","type":"stdio","command":"npx","args":["-y","@playwright/mcp@latest"]}'

This uses the VS Code format, not the portable Copilot user file. To choose a portable destination, use the guided connection flow. After installation, verify a tool call.

Editor-managed settings

These settings control the editor's MCP client, which the deprecated Local harness uses. They don't configure native Copilot discovery, startup, or sampling.

Related resources

• Add MCP servers
• Manage and troubleshoot MCP servers
• MCP tool extensibility overview