# How to debug MCP server connection issues

- Tool: MCP
- Difficulty: Intermediate
- Time required: 15-20 min
- Compatibility: All MCP hosts and servers
- Last updated: March 2026

## TL;DR

Debug MCP server connection issues systematically: first test the server manually in your terminal, then use MCP Inspector to verify the protocol layer, check your host configuration for JSON syntax errors, and finally review server logs for startup failures. Most connection problems come from incorrect paths, missing environment variables, or JSON config typos.

## Systematic Debugging of MCP Server Connections

When an MCP server fails to connect, the host typically shows a generic error or simply does not list the server's tools. Without a systematic approach, debugging can feel like guessing. This tutorial provides a step-by-step checklist that isolates the problem layer by layer: is the server binary accessible, does it start correctly, does the protocol handshake succeed, and is the host configuration valid?

## Before you start

- An MCP server that is failing to connect to your host
- Terminal access on your machine
- Node.js 18+ installed (for MCP Inspector)
- Access to your MCP host's configuration file

## Step-by-step guide

### 1. Test the server command manually in your terminal

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.

```
# Copy the exact command from your config and run it
# For npx-based servers:
npx -y @modelcontextprotocol/server-github

# For node-based servers:
node ./dist/index.js

# For Python servers:
uvx mcp-server-git --repository /path/to/repo

# Set environment variables first if needed:
export API_KEY="your-key"
node ./dist/index.js
```

**Expected result:** The server starts and waits for input (you may see a JSON-RPC initialization message), or you see a clear error that points to the cause.

### 2. Validate your host configuration JSON

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.

```
# Validate JSON from the command line
# macOS/Linux:
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

# If it outputs formatted JSON → valid
# If it outputs an error → fix the syntax

# Common issues:
# WRONG: trailing comma
{ "env": { "KEY": "value", } }

# RIGHT: no trailing comma
{ "env": { "KEY": "value" } }

# WRONG: unescaped backslash (Windows paths)
{ "args": ["C:\Users\name\server"] }

# RIGHT: escaped backslash
{ "args": ["C:\\Users\\name\\server"] }
```

**Expected result:** The JSON validator confirms your config file is valid JSON, or shows you the exact line with the syntax error.

### 3. Use MCP Inspector to test the protocol layer

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.

```
# Install and run MCP Inspector
npx -y @modelcontextprotocol/inspector

# For stdio servers, it will prompt you for the command
# For HTTP servers, specify the URL:
npx -y @modelcontextprotocol/inspector --transport http --url http://localhost:3000/mcp
```

**Expected result:** MCP Inspector connects to your server and displays available tools and resources, confirming the server is working at the protocol level.

### 4. Check MCP server logs for startup errors

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.

```
# Claude Desktop logs (macOS)
tail -n 50 -F ~/Library/Logs/Claude/mcp*.log

# Claude Desktop logs (Windows — in PowerShell)
Get-Content -Tail 50 -Wait "$env:APPDATA\Claude\logs\mcp.log"

# Cursor — check Output panel
# View → Output → select 'MCP' from dropdown
```

**Expected result:** You see the server's stderr output including any error messages, stack traces, or configuration warnings.

### 5. Verify environment variables are reaching the server

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.

```
// Add to your server's entry point for debugging
const requiredVars = ["API_KEY", "DATABASE_URL"];
for (const varName of requiredVars) {
  const isSet = !!process.env[varName];
  console.error(`  ${varName}: ${isSet ? "SET" : "MISSING"}`);
}

# Python equivalent
import os, sys
required_vars = ["API_KEY", "DATABASE_URL"]
for var in required_vars:
    is_set = var in os.environ
    print(f"  {var}: {'SET' if is_set else 'MISSING'}", file=sys.stderr)
```

**Expected result:** The server logs show which environment variables are set and which are missing, helping you identify configuration gaps.

## Complete code example

File: `debug-mcp-checklist.sh`

```bash
#!/bin/bash
# MCP Server Connection Debugging Checklist
# Run each step to isolate the problem

echo "=== Step 1: Check if server command exists ==="
which node
which npx
which uvx

echo ""
echo "=== Step 2: Validate config JSON ==="
CONFIG="$HOME/Library/Application Support/Claude/claude_desktop_config.json"
if [ -f "$CONFIG" ]; then
  python3 -m json.tool "$CONFIG" > /dev/null 2>&1
  if [ $? -eq 0 ]; then
    echo "Config JSON: VALID"
  else
    echo "Config JSON: INVALID — fix syntax errors"
    python3 -m json.tool "$CONFIG"
  fi
else
  echo "Config file not found at: $CONFIG"
fi

echo ""
echo "=== Step 3: Test server manually ==="
echo "Run your server command here, e.g.:"
echo "  npx -y @modelcontextprotocol/server-github"
echo "  node ./dist/index.js"
echo "  uvx mcp-server-git --repository /path"

echo ""
echo "=== Step 4: Check recent logs ==="
if ls ~/Library/Logs/Claude/mcp*.log 1> /dev/null 2>&1; then
  echo "Recent MCP log entries:"
  tail -n 20 ~/Library/Logs/Claude/mcp*.log
else
  echo "No MCP log files found"
fi

echo ""
echo "=== Step 5: Run MCP Inspector ==="
echo "npx -y @modelcontextprotocol/inspector"
```

## Common mistakes

- **Skipping the manual terminal test and jumping straight to config changes** — undefined Fix: Always test the server command in your terminal first. If it does not work there, no host configuration will fix it.
- **Editing the config file while the MCP host is running and expecting changes to apply** — undefined Fix: After editing the config, restart Claude Desktop completely or reload Cursor's window.
- **Not checking for JSON syntax errors in the config file** — undefined Fix: Use python3 -m json.tool or an online validator to check the config before restarting.
- **Ignoring the MCP server logs** — undefined Fix: Server logs contain the actual error messages. Check ~/Library/Logs/Claude/mcp*.log on macOS before making random changes.

## Best practices

- Follow the debugging checklist in order: command → config → protocol → logs
- Test server commands in terminal before adding them to host configs
- Validate JSON config files after every edit
- Use MCP Inspector as the definitive protocol-level test
- Add startup validation in your servers that logs which env vars are present
- Keep a tail -f on the log file while restarting the host to catch errors in real time
- Document working configurations so you can revert if something breaks

## Frequently asked questions

### My server works in the terminal but not in Claude Desktop. Why?

GUI applications like Claude Desktop do not inherit your shell's PATH or environment variables. Use absolute paths for commands (e.g., /opt/homebrew/bin/npx instead of npx) and set all required environment variables in the config's env block.

### How do I know if the problem is the server or the host?

Use MCP Inspector to test independently of the host. If Inspector connects and lists tools, the server is fine and the problem is in the host configuration. If Inspector also fails, the server itself has an issue.

### Can I debug MCP servers with a regular debugger?

Yes, for Node.js servers use --inspect flag: node --inspect ./dist/index.js, then connect Chrome DevTools. For Python, use debugpy. Note that breakpoints will pause the MCP protocol, so the host may time out.

### Why do all my MCP servers fail at once?

This almost always indicates a JSON syntax error in your config file. A single invalid character breaks the entire config, preventing all servers from loading. Validate the JSON first.

### The server connects but no tools appear. What is wrong?

The server is running but either has no tools registered, or the tool registration happens after the initialization handshake. Check your server code to ensure tools are registered before the server starts listening. Also check if there is a tool limit in your host (Cursor has a ~40 tool limit).

---

Source: https://www.rapidevelopers.com/mcp-tutorial/how-to-debug-mcp-server-connection-issues
© RapidDev — https://www.rapidevelopers.com/mcp-tutorial/how-to-debug-mcp-server-connection-issues