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 is stored in the mcp.json JSON file. This file can be in your workspace (.vscode/mcp.json) or in your user profile. VS Code provides IntelliSense for the configuration file.

Note

VS Code forwards the servers you configure to the Agent Host, except servers that require interactive input (for example, ${input:...} variables). The Agent Host doesn't read .vscode/mcp.json directly; for portable configuration, use a workspace .mcp.json or user ~/.copilot/mcp-config.json file, which the Agent Host reads natively. See behavior on the extension host.

Configuration structure

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.

Field Required Description Examples
type Yes Server connection type "stdio"
command Yes Command to start the server executable. Must be available on your system path or contain its full path. "npx", "node", "python", "docker"
args No Array of arguments passed to the command ["server.py", "--port", "3000"]
cwd No Working directory for the server command. Defaults to the workspace folder when run in a workspace. "${workspaceFolder}"
env No Environment variables for the server. Values can be strings, numbers, or null. {"API_KEY": "${input:api-key}"}
envFile No Path to an environment file to load more variables "${workspaceFolder}/.env"
dev No Development mode settings to watch for file changes and debug the server. See Development mode. {"watch": "src/**/*.ts"}
sandboxEnabled No Run the server in a sandboxed environment. Only supported on macOS and Linux. true
Note

When using Docker with stdio servers, don't use the detach option (-d). The server must run in the foreground to communicate with VS Code.

Example local server configuration

This example shows the minimal configuration for a basic, local MCP server using npx:

{
  "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. Sandboxed servers can only access the file system paths and network domains that you explicitly permit. Sandboxing is available on macOS and Linux only.

To enable sandboxing for a server, set \"sandboxEnabled\": true in its configuration. Then, define a top-level sandbox object to specify the file system and network access rules. The sandbox object is a sibling of servers and inputs, and its rules apply to all sandboxed servers. When a sandboxed server needs access that the current rules don't permit, check the server output for error messages and update the sandbox configuration accordingly.

Note

When sandboxing is enabled, tool confirmations are auto-approved because the server runs in a controlled environment.

The sandbox object supports the following properties:

Property Type Description
filesystem.allowWrite string[] File paths that the server is allowed to write to.
filesystem.denyRead string[] File paths that the server is not allowed to read.
filesystem.denyWrite string[] File paths that the server is not allowed to write to.
network.allowedDomains string[] Domains that the server is allowed to access. Wildcards are supported, for example *.example.com.
network.deniedDomains string[] Domains that the server is not allowed to access.

You can use