Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

“No MCP servers configured” means VS Code cannot find an MCP server in the workspace or in the active user profile. First confirm which workspace and profile are active. Then check that the configuration file and its top-level key match: .vscode/mcp.json uses servers, while a portable project-level .mcp.json uses mcpServers. If an entry exists, use MCP: List Servers and Show Output to distinguish a missing configuration from a server that is present but failing to start.

What the message means

VS Code is reporting an empty server list for the context currently in use. That context is determined by two things:

  • Scope: a workspace configuration or the active user profile.
  • Profile: VS Code profiles can have separate MCP configurations.

An empty list is therefore a configuration-discovery problem until the server entry is found and its startup output shows an error. Do not begin by deleting workspace state or reinstalling extensions.

VS Code’s current MCP guidance is documented in Add and manage MCP servers in VS Code (the page displayed a September 16, 2026 update). The configuration syntax is tied to the file you edit, so a valid JSON file can still be invisible if it uses the wrong top-level key.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
#1 Best Overall
Sale
Anker USB C Hub, 7in1 Multi-Port USB Adapter, 4K@60Hz USBC to HDMI Splitter
  • Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
  • Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
  • Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
  • Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
  • What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.

Fast diagnostic sequence

  1. Confirm the workspace. Look at the folder currently open in VS Code. A server stored in another project’s .vscode/mcp.json will not appear in this workspace.
  2. Confirm the profile. Open the Accounts or Manage menu and note the active profile. Profiles do not automatically share their MCP settings.
  3. Find the configuration file. Check .vscode/mcp.json in the workspace and, if your project uses the portable format, .mcp.json at the project root. For profile-wide servers, run MCP: Open User Configuration from the Command Palette.
  4. Check the key and scope together. Use servers in VS Code’s .vscode/mcp.json. Use mcpServers in the portable root .mcp.json.
  5. Ask VS Code to enumerate servers. Run MCP: List Servers. If the server is listed, select it and choose Show Output; it is no longer an “absent” server problem.
  6. Reload only after correcting the entry. Save the file, run Developer: Reload Window if the list does not refresh, and run MCP: List Servers again.

Fix a workspace configuration

VS Code format: .vscode/mcp.json

Create or edit .vscode/mcp.json under the workspace folder. The top-level object must be named servers:

{
  "servers": {
    "example": {
      "command": "npx",
      "args": ["-y", "example-mcp-server"]
    }
  }
}

Replace the command and arguments with the exact values supplied by the server publisher. The name example is only an identifier shown by VS Code; it is not a package name that will work by itself.

After saving, run MCP: List Servers. If the server appears but stays in a starting or error state, open Show Output for the next diagnosis instead of changing the file format.

Portable project format: .mcp.json

Some MCP clients and portable workspace setups use a file named .mcp.json at the project root. Its top-level key is different:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #2
Anker USB-C Hub, 5-in-1 USB Hub for Laptops, 4K HDMI Multiport Adapter
  • 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
  • 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
  • Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
  • 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
  • What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "example-mcp-server"]
    }
  }
}

Do not copy mcpServers into VS Code’s .vscode/mcp.json, and do not replace mcpServers with servers in a portable file. The file can remain syntactically valid while VS Code recognizes no entries because the schema and key do not match.

Add a server through VS Code

Use the guided command

Open the Command Palette with Ctrl+Shift+P on Windows or Linux, or Cmd+Shift+P on macOS, then run MCP: Add Server. Follow the prompts for the server type and command. This is useful when you are unsure which configuration file belongs to the current scope.

Install a gallery server

In the Extensions view, search for @mcp. Gallery entries can be installed for the workspace or for the user profile. If you install into a different profile than the one currently active, the server will appear to be missing until you switch back to that profile.

Open profile-wide settings directly

Run MCP: Open User Configuration. Servers in that file are available across workspaces that use the same profile. This is a different scope from a project’s .vscode/mcp.json, which can be shared with a team through source control.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #3
Anker USB C Hub, 5-in-1 USBC to HDMI Splitter with 4K Display
  • 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
  • Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
  • Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
  • HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
  • What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.

Choose the right scope

Question Workspace configuration User-profile configuration
Where is it stored? .vscode/mcp.json, or portable .mcp.json at the project root Open with MCP: Open User Configuration
Who can use it? The project’s workspace users, when the file is shared Any workspace using that VS Code profile on your account
Which key is used? servers in .vscode/mcp.json; mcpServers in portable .mcp.json The key shown by the profile configuration editor and current VS Code schema
When is it useful? Project-specific tools or a team-standard setup Personal tools used across multiple projects

For remote development, check the configuration in the environment where VS Code expects the connection to run. The current documentation distinguishes workspace and remote user configuration; a server configured only on your local machine may not be available in a remote workspace.

When the server is listed but will not start

Read the server output

Run MCP: List Servers, select the server, and choose Show Output. You can also use the output action on an MCP error notification in Chat. Capture the first error, the command VS Code attempted, and the exit code before changing multiple settings.

Check the executable and arguments

A local entry depends on the command being available in the environment that launches VS Code. Verify the runtime named in command is installed and on the PATH visible to VS Code. Check spelling, quoting, package names, required flags, and environment variables in args. If the publisher requires a particular working directory or token, follow those instructions rather than substituting a different command.

Docker-specific failure

If the server runs in Docker, inspect the command and its arguments. Do not start the container detached with -d for an MCP process that must communicate over its standard input and output; a detached container can leave VS Code waiting for a process it cannot use. The server’s output will usually show whether the container exited, could not find an image, or is waiting on the wrong transport.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #4
Sale
UGREEN USB C Hub 5 in 1 Multiport USB Adapter 4K HDMI, 100W Power Delivery
  • 5 in 1 Connectivity: The USB C Multiport Adapter is equipped with a 4K HDMI port, a 100W USB C PD port, a 5 Gbps USB A data port, and two 480 Mbps USB A ports

Remote-server entries

VS Code’s documented remote form uses a server entry with "type": "http" and a URL. Use the URL, authentication method, and any headers specified by that server’s publisher. Do not convert a remote HTTP entry into a local command entry unless the publisher provides a local executable.

Security checks before starting a local server

VS Code warns: “Local MCP servers can run arbitrary code on your machine.” Read the publisher’s setup instructions and the configuration before approving a local server. In particular:

  • Review every executable, package, argument, script, and downloaded artifact.
  • Keep access tokens out of files that will be committed to source control; use the environment-variable method supported by the server.
  • Be cautious with servers that can read project files, run shell commands, or make network requests.
  • For a team-shared workspace file, agree on the publisher, versioning, and credential handling before committing it.

Do not confuse an activation prompt with an empty server list

A historical VS Code issue recorded a separate bug in which an activation prompt could appear while VS Code was waiting for an MCP server to start. A maintainer wrote, “I identified a bug where we would incorrectly show this message if we were waiting for an MCP server to start.” The issue was opened October 12, 2025 and closed after a fix; see VS Code issue #270982.

That report concerns the activation message discussed in the issue, not every current empty-list state. Check the exact wording, your installed VS Code version, and the server output before attributing “No MCP servers configured” to that historical bug.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Best Value
Anker USB C Hub, USB Extender, 4-in-1 USB Splitter, Computer Accessories
  • Ultra-Fast Data Transfers: Experience the power of 5Gbps transfer speeds with this USB hub and sync data in seconds, making file transfers a breeze.
  • Long Cable, Endless Convenience: Say goodbye to short and restrictive cables. This USB hub comes with a 2 ft long cable, giving you the freedom to connect your devices exactly where you need them.
  • Sleek and Compact: Measuring just 4.2 × 1.2 × 0.4 inches, carry the USB hub in your pocket or laptop bag and connect effortlessly wherever you go.
  • Instant Connectivity: Anker USB-C data hub offers a true plug-and-play experience, instantly connecting your devices and enabling seamless file transfers.
  • What You Get: 2ft Anker USB-C Data Hub (4-in-1, 5Gbps) , welcome guide, our worry-free 18-month warranty, and friendly customer service.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Or skip the browser setup

If you need a clean screenshot of the VS Code MCP documentation, a project guide, or an internal status page while documenting your fix, ScreenshotNeo provides a single-call website screenshot API and MCP server. It accepts cookie and consent banners like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets before capture, and bills only clean shots. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; the response identifies the result with X-Page-Verdict and X-Billed headers.

Here is a runnable cURL request (replace only the access key and target URL):

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://code.visualstudio.com/docs/agent-customization/mcp-servers -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://code.visualstudio.com/docs/agent-customization/mcp-servers"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://code.visualstudio.com/docs/agent-customization/mcp-servers' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the full parameter reference and options in the ScreenshotNeo documentation. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. Every plan includes the features; the Free plan provides 1,000 screenshots per month without a card, and paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to get started.

Troubleshooting by symptom

Symptom Likely cause Action
The list is completely empty Wrong workspace, profile, file location, or top-level key Confirm the active context, then check .vscode/mcp.json with servers or portable .mcp.json with mcpServers.
The file is valid JSON but no server appears The schema does not match the file format Move the entry to the correct file or change only the top-level key required by that format.
The server appears and immediately exits Bad command, missing runtime, invalid argument, or missing environment variable Open Show Output; run the publisher’s command manually in the same environment and correct the first reported error.
Docker starts but Chat waits indefinitely The container was launched detached or uses the wrong transport Remove -d, keep the MCP process attached to its expected input/output, and verify the documented arguments.
The server exists in one project but not another It is workspace-scoped Install or configure it in the second workspace, or place it in the active profile’s user configuration.
A server appears after switching profiles The original profile had a separate configuration Keep using the profile containing the server or add the server to the intended profile with MCP: Open User Configuration.
A remote server works locally but not in a remote workspace The entry was configured in the wrong runtime location Configure it in the workspace or remote user context required by that environment, using the publisher’s remote instructions.

Final verification checklist

  • The active workspace is the project containing the intended configuration.
  • The intended VS Code profile is selected.
  • The file name and top-level key match: .vscode/mcp.json plus servers, or portable .mcp.json plus mcpServers.
  • The command, arguments, runtime, credentials, and transport match the server publisher’s instructions.
  • MCP: List Servers shows the entry.
  • Show Output contains a successful startup rather than an immediate exit or timeout.
  • The local server and its source have been reviewed before approval.

Frequently Asked Questions

What information should I include when asking for help with an MCP startup failure?

Include your VS Code version, active profile, whether the server is workspace or user scoped, the exact configuration file path, and the first error lines from Show Output. Remove access tokens and other secrets before posting logs.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Can I keep separate MCP setups for personal and work projects?

Yes. Use separate VS Code profiles for configurations that should not be shared, and use workspace files for project-specific servers. Check the active profile before assuming a server has disappeared.

Should MCP credentials be committed with the workspace file?

No. Keep secrets outside source control and use the credential or environment-variable mechanism documented by the server publisher.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.