MCP configuration reference

This article provides a reference for the MCP server configuration file format, related commands, and settings in VS Code. For information about adding and managing MCP servers, see Add and manage 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 servers from .vscode/mcp.json 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 and compatibility requirements, see configure MCP servers.

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.

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": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

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

Input variables for sensitive data

Input variables let you define placeholders for configuration values, avoiding the need to hardcode sensitive information like API keys or passwords directly in the server configuration.

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

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 and manage MCP servers
• Model Context Protocol Documentation
• MCP tool extensibility overview