MCP Server Troubleshooting Guide: Fix Common Issues & Errors 2026

MCP servers are powerful but their setup can be finicky. Configuration syntax errors, permission issues, missing environment variables, and runtime crashes are common — especially when first getting started. This guide covers the most frequent MCP server problems and exactly how to fix them.

Quick Diagnosis: How to See MCP Errors

Before debugging specific issues, know where to look for error output:

• Claude Desktop: Go to Help → Open MCP Log File (macOS/Linux: ~/Library/Logs/Claude/mcp*.log; Windows: %APPDATA%/Claude/logs/mcp*.log)
• Cursor: Open the Output panel (View → Output) and select "MCP" from the dropdown
• VS Code / Cline: Check the Output panel and look for the MCP server's output channel

Always check logs first. Most MCP failures produce clear error messages — the hard part is knowing where to find them.

Error: "Server not found" or MCP Server Won't Start

Cause: The MCP client can't find or execute the server command.

Fixes:

1. Check that Node.js is installed: Most MCP servers run via npx. Run node --version in your terminal — if it fails, install Node.js 18+ from nodejs.org.
2. Use absolute paths: The MCP client may use a different PATH than your terminal. Instead of npx, try the full path: /usr/local/bin/npx or $(which npx).
3. Check the command syntax: Make sure your JSON config is valid. A single missing comma or unclosed quote breaks the entire configuration file. Use a JSON validator at jsonlint.com before restarting.
4. Verify the package name: Package names change. Run the npx command manually in your terminal first to confirm it works and downloads correctly.

Error: "Connection timeout" or "Failed to connect"

Cause: The server starts but doesn't establish the MCP protocol handshake within the timeout window.

Fixes:

• Run the server command manually in your terminal first. If it produces errors immediately (missing API keys, port conflicts), you'll see them directly rather than through the client's log format.
• Check for startup crashes: Some servers crash silently if required environment variables aren't set. Check the server's README for required environment variables.
• Port conflicts (rare): Some MCP servers run an HTTP server on a specific port. Check if another process is using that port with lsof -i :PORT.

Error: "Tool not found" or "No tools available"

Cause: The MCP client connected to the server but couldn't load its tool definitions.

Fixes:

• Check server version compatibility: If you installed a server globally (npm install -g) months ago, it may not support the current MCP protocol version. Uninstall and reinstall: npm uninstall -g package-name && npx package-name@latest.
• Use -y flag with npx: Add -y to your npx command (npx -y package-name) to auto-accept the install prompt. Without it, the server may hang waiting for confirmation.
• Restart the client: Claude Desktop and Cursor sometimes cache the tool list from a previous session. Fully quit and reopen the application.

Error: Authentication / API Key Issues

Cause: The server starts but can't authenticate with the external service (GitHub, database, etc.).

Fixes:

• Environment variables not loading: MCP clients start servers in a clean environment. Variables set in your shell profile (.bashrc, .zshrc) are NOT automatically available. You must explicitly include them in the MCP config's env block.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_yourtokenhere"
      }
    }
  }
}

• Expired tokens: GitHub PATs, API keys, and database credentials expire or get revoked. Test your credentials independently (e.g., curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user) before assuming the MCP server is at fault.
• Permissions scope: For GitHub, your PAT needs the right scopes. A PAT without repo scope can't access private repositories. Review the server's documentation for required permission scopes.

Database Connection Failures (PostgreSQL, MySQL, etc.)

Database MCP servers fail for predictable reasons:

• Connection string format: PostgreSQL expects postgresql://user:pass@host:5432/dbname. A missing port, incorrect user, or wrong database name causes a connection failure. Test the connection string directly: psql "postgresql://user:pass@host:5432/dbname".
• Network access: If your database is remote, ensure the MCP server's host machine is whitelisted in your database's firewall or security group.
• SSL requirements: Many hosted databases (Supabase, Neon, Railway) require SSL. Add ?sslmode=require to your connection string if you see SSL-related errors.
• Read-only mode: Some MCP servers default to read-only mode for safety. If you need write access, check the server's configuration options to enable it explicitly.

Filesystem MCP Server Issues

• Permission denied errors: The Filesystem server restricts access to the directories you configure. Make sure the path in your config matches the actual directory you want to access. Use absolute paths, not ~ shortcuts (expand to /Users/yourname/...).
• Path doesn't exist: The directory must exist before the server starts. Create it if needed.
• Symlinks: Some Filesystem server implementations don't follow symlinks by default. If your project uses symlinks (common in monorepos with workspaces), check if the server supports --follow-symlinks.

Claude Desktop: Config File Location

The most common mistake for Claude Desktop users is editing the wrong config file. The MCP configuration lives at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%Claudeclaude_desktop_config.json

After any config change, fully quit Claude Desktop (Cmd+Q on Mac, not just closing the window) and reopen it. The app doesn't hot-reload config changes.

General Debugging Checklist

1. Check logs (location varies by client — see top of this guide)
2. Run the server command manually in your terminal to see direct errors
3. Validate your JSON config syntax
4. Confirm environment variables are in the config's env block, not just your shell
5. Test credentials independently before blaming the MCP server
6. Fully restart (quit + reopen) your MCP client after any config change
7. Check the server's GitHub Issues page — your error may already have a known fix

Browse specific setup guides for individual servers on MyMCPTools server pages, each includes installation and troubleshooting notes. You can also find more help in the getting started guide.