How to debug MCP server connection issues

The first step is to verify that the server binary can actually run. Open your terminal and execute the exact command from your MCP host config. If the server uses npx, run the full npx command. If it uses node or uvx, run that. A working server will output JSON-RPC messages to stdout and wait for input. If you see an error instead, the problem is in the server itself — not the host connection. Common failures include command not found, missing dependencies, or missing environment variables.

1# Copy the exact command from your config and run it
2# For npx-based servers:
3npx -y @modelcontextprotocol/server-github
4
5# For node-based servers:
6node ./dist/index.js
7
8# For Python servers:
9uvx mcp-server-git --repository /path/to/repo
10
11# Set environment variables first if needed:
12export API_KEY="your-key"
13node ./dist/index.js

A single misplaced comma or missing quote in your config file will prevent all MCP servers from loading. Copy your entire configuration file content and paste it into a JSON validator (like jsonlint.com or your IDE's built-in JSON validation). Common JSON syntax errors include trailing commas after the last item in an object, missing closing braces, and unescaped backslashes in Windows file paths.

1# Validate JSON from the command line
2# macOS/Linux:
3cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool
4
5# If it outputs formatted JSON → valid
6# If it outputs an error → fix the syntax
7
8# Common issues:
9# WRONG: trailing comma
10{ "env": { "KEY": "value", } }
11
12# RIGHT: no trailing comma
13{ "env": { "KEY": "value" } }
14
15# WRONG: unescaped backslash (Windows paths)
16{ "args": ["C:\Users\name\server"] }
17
18# RIGHT: escaped backslash
19{ "args": ["C:\\Users\\name\\server"] }

MCP Inspector is an official debugging tool that acts as an MCP client and connects to your server. It shows you the initialization handshake, lists available tools and resources, and lets you execute tool calls interactively. If the Inspector can connect but your host cannot, the problem is in the host configuration. If the Inspector also fails, the problem is in the server itself.

1# Install and run MCP Inspector
2npx -y @modelcontextprotocol/inspector
3
4# For stdio servers, it will prompt you for the command
5# For HTTP servers, specify the URL:
6npx -y @modelcontextprotocol/inspector --transport http --url http://localhost:3000/mcp

MCP hosts capture server stderr output in log files. Claude Desktop on macOS writes logs to ~/Library/Logs/Claude/mcp*.log. On Windows, check %APPDATA%\Claude\logs\. Cursor shows MCP errors in the Output panel (select MCP from the dropdown). These logs often contain the exact error message that explains why the server failed to start.

1# Claude Desktop logs (macOS)
2tail -n 50 -F ~/Library/Logs/Claude/mcp*.log
3
4# Claude Desktop logs (Windows — in PowerShell)
5Get-Content -Tail 50 -Wait "$env:APPDATA\Claude\logs\mcp.log"
6
7# Cursor — check Output panel
8# View → Output → select 'MCP' from dropdown

If your server starts but fails because of missing API keys, the env block in your config may not be reaching the server process. Add a startup check to your server that logs which environment variables are set (without logging the actual values). This confirms whether the host is injecting the variables correctly. If you have exhausted these debugging steps and still cannot resolve the issue, the RapidDev team has experience debugging complex MCP configurations and can help identify the root cause.

1// Add to your server's entry point for debugging
2const requiredVars = ["API_KEY", "DATABASE_URL"];
3for (const varName of requiredVars) {
4  const isSet = !!process.env[varName];
5  console.error(`  ${varName}: ${isSet ? "SET" : "MISSING"}`);
6}
7
8# Python equivalent
9import os, sys
10required_vars = ["API_KEY", "DATABASE_URL"]
11for var in required_vars:
12    is_set = var in os.environ
13    print(f"  {var}: {'SET' if is_set else 'MISSING'}", file=sys.stderr)