VS Code MCP Setup Guide: mcp.json and Servers

Quick setup

VS Code supports MCP servers through its MCP gallery, the MCP: Add Server command, and manual mcp.json configuration.

For a remote HTTP server in one repository, create .vscode/mcp.json:

{
  "servers": {
    "projectApi": {
      "type": "http",
      "url": "https://api.example.com/mcp"
    }
  }
}

Open the Command Palette and run MCP: List Servers to start, stop, inspect, or troubleshoot the server. In chat, use Configure Tools to review which MCP tools are available and disable tools the current task does not need.

The current official VS Code MCP documentation supports remote HTTP and local stdio servers. The configuration format is not interchangeable with Cursor or Claude Code: VS Code uses a top-level servers object, workspace configuration lives at .vscode/mcp.json, and sensitive values can use VS Code input variables.

VS Code MCP setup options

Choose workspace scope when the server belongs to one repository and the definition is safe to share. Choose user scope for personal documentation or workflow servers needed across projects. If you are connected through SSH, WSL, a Dev Container, or another remote environment, define a local-process server in the environment where it must actually run.

How to add an MCP server to VS Code

Step 1: choose a trusted server

Begin with the provider's official documentation or source repository. Review:

• publisher and server operator
• remote URL or local command
• read and write tools
• OAuth scopes, API keys, and backend credentials
• files, network domains, repositories, or production systems the server can reach
• update and revocation process

The VS Code MCP gallery is useful for discovery, but installation is still a security decision. A local server can execute code with the user's authority, while a remote server can receive selected context and act with the connected account's permissions.

Use the best MCP servers comparison to shortlist workflow-specific options before installing a package from an old blog post or copied configuration.

Step 2: install from the MCP gallery

Open the Extensions view and search:

@mcp

Select a server to review its publisher and details. Choose Install for the current user profile or Install in Workspace for one repository. Workspace installation updates .vscode/mcp.json.

When VS Code asks whether you trust the server, inspect its configuration before starting it. Trusting a server allows VS Code to launch its command or connect to its endpoint and discover capabilities.

Step 3: use MCP: Add Server

Open the Command Palette and run:

MCP: Add Server

Choose the server type, provide the command or remote URL, and select Workspace or Global. This guided path is useful when a server is not in the gallery but does not require a complex hand-written configuration.

Step 4: configure VS Code mcp.json

Use manual configuration when the repository needs a reviewed server definition, authentication input, environment file, or multiple servers.

A remote HTTP server requires type and url:

{
  "servers": {
    "projectApi": {
      "type": "http",
      "url": "https://api.example.com/mcp"
    }
  }
}

A local stdio server uses a command and arguments:

{
  "servers": {
    "browserTools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "example-mcp-package"]
    }
  }
}

The top-level key is servers, not mcpServers. Cursor and Claude Code examples commonly use mcpServers; copying them unchanged into VS Code causes configuration errors.

Step 5: keep secrets out of Git

Do not hardcode an API key in .vscode/mcp.json. Use a password input so VS Code prompts once and stores the value separately:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "project-mcp-token",
      "description": "Project MCP API token",
      "password": true
    }
  ],
  "servers": {
    "projectApi": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:project-mcp-token}"
      }
    }
  }
}

VS Code also supports environment files for local stdio server variables. Commit only a secret-free server definition and document where each developer obtains the required credential.

Step 6: start and verify the server

Run MCP: List Servers, select the server, and inspect its status. If it fails, choose Show Output to open the MCP server log.

In chat:

1. select Configure Tools
2. find the server
3. inspect and narrow its enabled tools
4. request one harmless read-only action
5. review the proposed tool call
6. test one operation that policy should deny

A connected status proves transport and authentication. It does not prove that backend permissions, tenant boundaries, or write restrictions are correct.

VS Code mcp.json locations

VS Code supports two primary configuration locations:

Each VS Code profile can have its own MCP configuration. With Settings Sync enabled, users can choose to synchronize MCP server configurations across devices.

For remote development, use MCP: Open Remote User Configuration when a local-process server must run on the remote host. A server configured in the local user profile runs locally even while the editor is attached to another environment.

Remote HTTP, OAuth, and API keys

For HTTP servers, VS Code first uses the current HTTP transport and can fall back to SSE when required by an older endpoint. Prefer HTTP for a new remote setup.

A provider can use OAuth:

{
  "servers": {
    "provider": {
      "type": "http",
      "url": "https://provider.example.com/mcp",
      "oauth": {
        "clientId": "YOUR_REGISTERED_CLIENT_ID"
      }
    }
  }
}

When OAuth is configured, VS Code opens a browser window for authorization on first connection. Follow the provider's current instructions rather than inventing a client ID; many hosted servers use their own discovery and registration flow.

For a fixed API key, use an input variable in headers. A 401 usually means the credential is missing or rejected. A 403 can mean the identity is valid but lacks the required scope or backend permission.

Local server sandboxing

VS Code can sandbox locally running stdio MCP servers on macOS and Linux. Sandboxing can restrict filesystem writes, denied paths, and allowed network domains.

{
  "servers": {
    "localTool": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "example-mcp-package"],
      "sandboxEnabled": true
    }
  },
  "sandbox": {
    "filesystem": {
      "allowWrite": ["${workspaceFolder}"]
    },
    "network": {
      "allowedDomains": ["api.example.com"]
    }
  }
}

Sandboxing reduces local process access but does not validate the server's tool semantics or the permissions of remote accounts it calls. Review the restrictions carefully because VS Code can auto-approve tool calls from a sandboxed server.

VS Code MCP examples

GitHub MCP server

GitHub's hosted server uses a remote endpoint. Follow GitHub's current authentication guidance and restrict access to the repositories and operations required by the project:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp"
    }
  }
}

Repository reading, issue creation, pull-request updates, and administrative operations should not receive the same default permission set.

Hosted PostgreSQL or OpenAPI through datamcp

Full disclosure: datamcp is our product.

datamcp publishes a remote HTTP MCP endpoint for PostgreSQL 12+ or an OpenAPI 3.x / supported Swagger or Redoc source. A VS Code workspace can reference the endpoint while prompting each developer for a datamcp API key:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "datamcp-api-key",
      "description": "DataMCP API key",
      "password": true
    }
  ],
  "servers": {
    "appSource": {
      "type": "http",
      "url": "https://api.datamcp.app/api/mcp/YOUR_CONNECTION_ID",
      "headers": {
        "Authorization": "Bearer ${input:datamcp-api-key}"
      }
    }
  }
}

The PostgreSQL or upstream API credential remains on the datamcp connection rather than in the repository.

For PostgreSQL, each MCP link can use read-only, read-write, full-access, or custom table-level operations. The connected database role remains an additional permission boundary, and PostgreSQL query activity and denied operations are available for review.

For OpenAPI, datamcp exposes four schema-aware tools for listing endpoints, inspecting details and schemas, and calling approved operations. Read Only permits visible GET and HEAD methods. OpenAPI calls do not currently appear in the datamcp activity log, so use the upstream API and infrastructure logs for execution evidence.

Use the VS Code PostgreSQL MCP integration for the commercial product path or OpenAPI to MCP for a REST API.

VS Code MCP troubleshooting

Server is missing

• Confirm workspace configuration is exactly .vscode/mcp.json.
• Confirm the top-level key is servers.
• Run MCP: Open Workspace Folder Configuration to open the file VS Code is actually reading.
• Check whether the server was installed in a different user profile.
• Run MCP: List Servers and verify that the server is enabled for the workspace.

Remote server returns 401 or 403

• Re-enter the secure input or repeat the provider's OAuth flow.
• Confirm the endpoint URL and authorization header format.
• Check whether the API key, MCP link, or provider session was revoked.
• Verify account, repository, project, database, or tenant permissions.
• Remove a fixed header if the provider expects OAuth instead.

Local server fails to start

• Select Show Output from MCP: List Servers.
• Run the configured command directly in a terminal.
• Confirm the required runtime is installed in the environment where the server runs.
• Do not use detached mode for a Docker stdio server.
• Check args, cwd, env, and envFile paths.
• Update sandbox rules only after reviewing the denied file or network access.

Server connects but tools are unavailable

• Open Configure Tools and verify the server's tools are enabled.
• Restart the server after changing mcp.json.
• Confirm the authenticated account can access the required resource.
• Check organization policies that restrict MCP servers or tools.
• Clear cached tools from the server management actions when the provider changed its tool list.

Configuration works locally but not in a remote workspace

The local user configuration runs local processes on the local machine. Move the definition to workspace, remote user, or Dev Container configuration when the server must run beside the remote repository or service.

VS Code MCP FAQ

How do I add an MCP server to VS Code?

Install it from the MCP gallery with @mcp, run MCP: Add Server from the Command Palette, or add a server definition to .vscode/mcp.json. Then use MCP: List Servers and Configure Tools to verify the connection and available tools.

Where is the VS Code MCP config file?

Workspace configuration is stored in .vscode/mcp.json. User-level configuration is stored in the current VS Code profile and opens through MCP: Open User Configuration.

Does VS Code use servers or mcpServers?

VS Code uses the top-level servers key. Cursor and Claude Code commonly use mcpServers, so their JSON files should not be copied into VS Code without adapting the schema and file location.

Can VS Code connect to a remote MCP server?

Yes. Set "type": "http" and provide the remote url. VS Code supports OAuth configuration and authentication headers for remote servers.

Should .vscode/mcp.json be committed?

Commit it when the server definition is intentionally shared with the repository and contains no hardcoded secret. Use VS Code input variables or an environment file for credentials, and review every local command before accepting changes from a branch or pull request.

How do I see MCP server logs in VS Code?

Run MCP: List Servers, select the affected server, and choose Show Output. The output identifies startup, transport, authentication, and tool-discovery errors.

For the next step, compare the best MCP servers by workflow, review the production MCP security checklist, or create one PostgreSQL connection and one MCP link on the Free plan.