nexus-mcp/MCP_TROUBLESHOOTING.md

MCP Server Troubleshooting Guide

Issue: MCP Server Not Showing in VS Code Copilot

What We've Done

1. ✅ Updated .vscode/settings.json with full Python path
2. ✅ Added PYTHONPATH and PYTHONUNBUFFERED environment variables
3. ✅ Verified server has proper mcp.run(transport="stdio") setup
4. ✅ Created alternative configuration file

Diagnostic Steps

1. Check VS Code Output Panel

How:

1. Open: View → Output
2. Select dropdown: GitHub Copilot Chat
3. Look for MCP-related errors

What to look for:

• Failed to start MCP server "nexus"
• Python not found
• Module not found
• Any error mentioning "nexus" or "mcp"

2. Verify Copilot Extension Version

Required: GitHub Copilot extension v0.12.0 or newer

Check:

1. Extensions panel (Ctrl+Shift+X)
2. Search: "GitHub Copilot"
3. Check version number
4. Update if needed

Note: MCP support is a recent feature. Older versions won't recognize MCP servers.

3. Verify Settings Location

Workspace vs User Settings:

The configuration should be in workspace settings, not user settings.

Check:

.vscode/settings.json  ← Should be here (workspace)

Not here:

%APPDATA%\Code\User\settings.json  ← User settings (wrong location)

4. Alternative Configuration Locations

VS Code Copilot may look for MCP servers in:

Option A: Workspace settings (recommended)

.vscode/settings.json

Option B: User-level MCP config

%APPDATA%\Code\User\globalStorage\github.copilot-chat\mcp_settings.json

I've created mcp_settings.json in the workspace root as an alternative.

To use Option B:

1. Copy mcp_settings.json to the user-level path above
2. Create the directory if it doesn't exist
3. Reload VS Code

5. Test Server Manually

Verify the server can start:

cd nexus-mcp
.venv\Scripts\python.exe src\main.py

Expected: Server starts and waits for stdio input (no output is normal) Press Ctrl+C to exit

If this fails, there's a problem with the server itself (not VS Code config).

6. Check for Python Path Issues

Current configuration uses:

${workspaceFolder}/nexus-mcp/.venv/Scripts/python.exe

Test if VS Code resolves this:

1. Open Terminal in VS Code
2. Run: echo ${workspaceFolder}
3. Should show: C:\Users\castn1.CORP\OneDrive - Wheels\Repos\mcp_servers

If blank, VS Code can't resolve workspace variables.

Workaround: Use absolute path in settings.json:

"command": "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/.venv/Scripts/python.exe"

Common Issues & Solutions

Issue: "command not found: python"

Solution: Use absolute path to Python:

"command": "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/.venv/Scripts/python.exe"

Issue: "No such file or directory: main.py"

Solution: Check cwd is correct:

"cwd": "${workspaceFolder}/nexus-mcp"

Issue: "Module not found" errors

Solution: Add PYTHONPATH:

"env": {
  "PYTHONPATH": "${workspaceFolder}/nexus-mcp/src:${workspaceFolder}/nexus-mcp/lib"
}

Issue: Server starts but tools don't appear

Possible causes:

1. Copilot extension too old (update to v0.12.0+)
2. MCP protocol mismatch
3. Server responding but not following MCP spec

Debug: Check Copilot output panel for protocol errors

Alternative: Use Claude Desktop Instead

If VS Code Copilot continues to have issues, you can use Claude Desktop with the same MCP server:

Location: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nexus": {
      "command": "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/.venv/Scripts/python.exe",
      "args": [
        "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/src/main.py"
      ],
      "env": {
        "USE_MOCK": "true",
        "ENABLE_AUDIT": "true"
      }
    }
  }
}

Still Not Working?

Try this minimal test:

1. Create a simple MCP server test:

# test_simple_mcp.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("test")

@mcp.tool()
def hello() -> str:
    """Say hello"""
    return "Hello from MCP!"

if __name__ == "__main__":
    mcp.run(transport="stdio")

2. Add to settings.json:

"github.copilot.chat.mcpServers": {
  "test": {
    "command": "python",
    "args": ["${workspaceFolder}/test_simple_mcp.py"]
  }
}

3. Reload VS Code
4. Try @test in Copilot Chat

If this works, the issue is with the Nexus server. If not, it's a VS Code/Copilot configuration issue.

Report Issues

If none of these work, the issue may be:

1. VS Code Copilot doesn't support MCP yet on your version
2. Feature not available in your region/license
3. Bug in Copilot extension

Check: https://github.com/microsoft/vscode-copilot/issues