MCP configuration reference

This article provides the MCP configuration formats, supported fields, commands, and settings in VS Code. To connect your first server, see Add MCP servers. For operational tasks, see Manage and troubleshoot MCP servers.

Configuration file

MCP server configuration uses one of the following file formats:

• The VS Code format is stored in .vscode/mcp.json in your workspace or in your user profile. It defines servers in a top-level servers object. VS Code provides IntelliSense for this format.
• The portable Copilot format is stored in .mcp.json at the root of your workspace or in $COPILOT_HOME/mcp-config.json for your user, with ~/.copilot/mcp-config.json as the fallback location. It defines servers in a top-level mcpServers object.

Copilot harness sessions read the portable format directly. VS Code forwards eligible servers from the VS Code format to the session, except servers that require interactive input, such as ${input:...} variables. The agent doesn't read .vscode/mcp.json directly. For setup steps, see Choose a configuration destination.

For other providers, use the provider's MCP configuration documentation. Their configuration locations and schemas can differ from the two formats described here.

The formats and locations differ in the capabilities they support:

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": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

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"
    }
  }
}

Follow the Context7 setup instructions for authentication and service limits. An endpoint alone doesn't grant access to a service.

The property tables below describe the VS Code format, not a shared schema for all MCP clients. Check the capability comparison before copying properties 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 MCP configuration form. The form writes the configured values to the file. Enter references rather than literal credentials.

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.

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 configuration for servers that communicate through standard input and output streams. This is the most common type for locally-run MCP servers.

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

Sandbox configuration

You can enable sandboxing for locally-running stdio MCP servers to restrict their access to the file system and network. Sandbox rules can deny file access, grant write access, and grant access to specific network domains. Sandboxing is available on macOS and Linux only.

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 configuration for servers that communicate over HTTP. VS Code first tries the HTTP Stream 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"
      }
    }
  }
}

Authentication and secrets

Authentication grants access to an external service. It is separate from trusting a server to start and approving individual tool calls.

Choose an authentication method that both the server and your configuration support:

Do not commit tokens, passwords, or populated authentication headers. A personal configuration file is not a secret store. For a server that requires a fixed token, follow its publisher's secure configuration guidance for your client and harness rather than copying credentials into a shared example.

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.

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

You can enable development mode for MCP servers by adding a dev key to the server configuration. This is an object with 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 Dev Guide.

Server naming conventions

When defining MCP servers, follow these naming conventions for the server name:

• Use camelCase for the server name, such as "uiTesting" or "githubIntegration"
• Avoid using whitespace or special characters
• Use a unique name for each server to avoid conflicts
• Use a descriptive name that reflects the server's functionality or brand, such as "github" or "database"

Automatic MCP server discovery

VS Code 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 the discovery sources.

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.

Commands

The following table lists the MCP-related commands available in the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

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.

Settings

For a full list of VS Code AI settings, see the AI Settings Reference. The following settings are specific to MCP servers.

Related resources

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