MCP Server Isn’t Working? Try These Solutions First

The Model Context Protocol (MCP) server is a core component for extending Visual Studio Code’s chat capabilities with external tools and services.

Whether you’re using MCP servers for file operations, database interactions, or API integrations, unexpected downtime or malfunctions can disrupt your workflow.

Before seeking advanced support, follow this step-by-step troubleshooting guide to resolve common issues efficiently, leveraging VS Code’s built-in features and best practices from official documentation.

1. Verify Basic Environment Prerequisites

Many MCP server issues stem from incomplete setup or outdated dependencies. Start with these foundational checks:

• Update VS Code: MCP support is generally available from VS Code 1.102 onwards. Outdated versions may have compatibility bugs. Go to Help > Check for Updates to install the latest release (Version 1.108 as of this guide). Dismiss any pending update notifications that might interfere with background processes.
• Confirm Copilot Access: MCP servers require active Copilot access. Ensure your account has a valid subscription and is signed in to VS Code (check the status bar for Copilot indicators).
• Check Dependencies: For locally run MCP servers (e.g., Node.js, Python-based), verify that the required runtime environments are installed and accessible in your system path. Use terminal commands like node --version or python --version to confirm availability.

2. Resolve Server Trust and Startup Issues

MCP servers may fail to start if they’re untrusted or misconfigured for auto-start. Address these scenarios first:

• Confirm Server Trust: Local MCP servers can execute arbitrary code, so VS Code requires explicit trust. If the server didn’t start after installation, check for a trust prompt—select the server link to review its configuration, then confirm trust. To reset trust for existing servers, run MCP: Reset Trust from the Command Palette (⌘⇧P on macOS, Ctrl+Shift+P on Windows/Linux).
• Manual Start/ Restart: Use the MCP: List Servers command to locate your server, then select Start or Restart. For workspace-specific servers, right-click the server in the Extensions view (⇧⌘X) and choose the appropriate action. Avoid starting servers directly from mcp.json, as this bypasses trust validation.
• Enable Auto-Start (Experimental): If the server fails to restart after configuration changes, enable chat.mcp.autostart in VS Code settings. This ensures the server reloads automatically when updates are detected.

3. Validate Server Configuration

Incorrect entries in themcp.json configuration file are a leading cause of MCP server failures. Focus on these key checks:

• Check Transport Type Compatibility:
  • For stdio servers (local executables), ensure the command field points to a valid executable (e.g., node, python) and args are correctly formatted. Avoid the Docker d (detach) option—servers must run in the foreground to communicate with VS Code.
  • For HTTP/SSE servers, verify the url is reachable (e.g., http://localhost:3000) and headers (e.g., authentication tokens) are valid. For Unix sockets or Windows named pipes, use the correct format: unix:///path/to/server.sock or pipe:///pipe/named-pipe.
• Secure Input Variables: If your configuration uses ${input:variable-id} for sensitive data (API keys, tokens), ensure the inputs section in mcp.json is properly defined. VS Code prompts for these values on first startup—re-enter them by resetting the server or running MCP: List Servers > Restart.
• Follow Naming Conventions: Use camelCase for server names (e.g., githubIntegration), avoid whitespace/special characters, and ensure uniqueness to prevent conflicts.

4. Clear Cached Tools and Refresh Capabilities

VS Code caches MCP server tools on first startup. Corrupted cache can cause tools to not load or behave unexpectedly:

1. Open the Command Palette and run MCP: Reset Cached Tools. This clears the stored list of tools for all MCP servers.
2. Restart the affected MCP server to trigger a fresh discovery of its capabilities.
3. If tools still don’t appear, use MCP: Browse Resources to verify the server is exposing tools correctly.

5. Analyze Server Logs for Errors

VS Code’s MCP output log provides detailed insights into startup failures and runtime errors. Access it using these steps:

1. Look for an error indicator in the Chat view (💥 icon). Select the notification and choose Show Output.
2. Alternatively, run MCP: List Servers, select the problematic server, and click Show Output.
3. Common log errors to look for:
   1. Missing dependencies (e.g., “Module not found” for Node.js servers).
   2. Port conflicts (for HTTP servers) or invalid file paths (for stdio servers).
   3. Authentication failures (invalid API keys in headers or input variables).

6. Address Tool Limit and Network Restrictions

Two common environment-specific issues can block MCP server functionality:

• Tool Quantity Limit: If you see “Cannot have more than 128 tools per request,” reduce the number of enabled tools. Open the Chat view’s tool picker (Tools button) and deselect unused tools/servers. Enable github.copilot.chat.virtualTools.threshold to optimize tool usage for large setups.
• Enterprise/ Network Restrictions: Your organization may block MCP servers via GitHub policies. Contact your admin to confirm access permissions. For network issues, check firewalls/proxies that might block the server’s URL (for HTTP/SSE) or executable path (for stdio).

7. Advanced Debugging with Development Mode

For custom or community-contributed MCP servers, enable development mode to debug runtime issues:

See also: Mastering the Linux Command Line — Your Complete Free Training Guide

1. Add a dev object to your server’s configuration in mcp.json: { "servers": { "myCustomServer": { "type": "stdio", "command": "node", "args": ["server.js"], "dev": { "watch": "*.js", // Restart on file changes "debug": true // Enable debugger integration } } } }
2. VS Code supports debugging for Node.js and Python MCP servers. Use the Run and Debug view to set breakpoints and diagnose code-level issues.

8. Reinstall or Reconfigure the Server

If all else fails, reset the server to its default state:

• Uninstall the server via the Extensions view (right-click > Uninstall) or MCP: List Servers > Uninstall.
• Delete residual configuration entries in mcp.json (access via MCP: Open User Configuration or Open Workspace Folder Configuration).
• Reinstall the server from the GitHub MCP registry (search@mcp in Extensions) or re-add it via the original configuration method.