Pjt222 Agent Almanac Troubleshoot MCP Connection

Troubleshoot MCP Connection

Diagnose, resolve MCP server connection failures.

When Use

• Claude Code or Claude Desktop fails connect to MCP server
• MCP tools don't appear in sessions
• "Cannot attach server" errors
• Connection worked, now stopped
• Set up MCP on new machine

Inputs

• Required: Error message or symptom description
• Required: Which client (Claude Code, Claude Desktop, both)
• Required: Which MCP server (mcptools, Hugging Face, custom)
• Optional: Recent changes to config or environment

Steps

Step 1: Identify Client and Config

Claude Code (WSL):

# View MCP configuration
claude mcp list
claude mcp get server-name

# Configuration stored in
cat ~/.claude.json | python3 -m json.tool

Claude Desktop (Windows):

# Configuration file location
cat "/mnt/c/Users/$USER/AppData/Roaming/Claude/claude_desktop_config.json"

Got: Config file located, readable. Shows MCP server entries with command, args, env fields.

If fail: Config file missing or empty? Server never configured. Use configure-mcp-server skill — set up from scratch.

Step 2: Test Server Independent

R mcptools:

# Test if R can start the server
"/mnt/c/Program Files/R/R-4.5.0/bin/Rscript.exe" -e "mcptools::mcp_server()"

If fail:

• Check R path: ls "/mnt/c/Program Files/R/"
• Check mcptools installed: Rscript -e "library(mcptools)"
• Check ellmer dep: Rscript -e "library(ellmer)"

Hugging Face MCP:

# Test mcp-remote directly
mcp-remote https://huggingface.co/mcp

# Check if mcp-remote is installed
which mcp-remote
npm list -g mcp-remote

Got: Server process starts. Produces init output (JSON-RPC handshake or "listening" msg). No errors.

If fail: R mcptools fails? Check R version path correct, mcptools installed in R library. mcp-remote fails? Reinstall global with npm install -g mcp-remote. Verify on PATH.

Step 3: Diagnose Common Error Patterns

"Cannot attach server" (Claude Desktop)

Root cause: Windows command argument parsing.

Fix: Use env vars instead of --header args:

{
  "hf-mcp-server": {
    "command": "mcp-remote",
    "args": ["https://huggingface.co/mcp"],
    "env": { "HF_TOKEN": "your_token" }
  }
}

Also ensure mcp-remote global installed (npm install -g mcp-remote) — no rely on npx.

"Connection refused"

• Server not running or wrong port
• Firewall blocks connection
• Wrong transport type (stdio vs HTTP)

"Command not found"

• Missing full path to executable
• PATH not configured in execution context
• On Windows: use C:\\PROGRA~1\\... for paths with spaces

MCP tools don't appear, no error

• Server starts but tools not registered
• Check server stdout for init messages
• Verify server uses correct MCP protocol version

Got: Error pattern matched to one documented category (cannot attach, connection refused, command not found, silent failure).

If fail: Error matches no known pattern? Capture full error output. Check server-side logs. Search exact error in MCP server's GitHub issues.

Step 4: Check Network and Auth

# Test Hugging Face API connectivity
curl -I "https://huggingface.co/mcp"

# Verify token validity
curl -H "Authorization: Bearer $HF_TOKEN" https://huggingface.co/api/whoami

Got: HTTP endpoint returns 200. whoami returns Hugging Face username. Network and auth OK.

If fail: curl returns connection error? Check DNS, proxy. Token rejected (401)? Regenerate at huggingface.co/settings/tokens. Update config.

Step 5: Verify JSON Config Syntax

# Validate JSON (common issue: trailing commas, missing quotes)
python3 -m json.tool /path/to/config.json

Got: JSON parses, no errors. Config syntax valid.

If fail: Common JSON issues — trailing commas after last entry, missing quotes around strings, mismatched braces. Fix syntax error from parser. Re-validate.

Step 6: Platform-Specific Debugging

Windows (Claude Desktop):

• Arg parsing differs from Unix
• Spaces in paths break command execution
• Use 8.3 short paths: C:\PROGRA~1\R\R-45~1.0\bin\x64\Rscript.exe
• Env vars more reliable than command-line headers

WSL (Claude Code):

• Unix-style quoting works
• Full paths with spaces OK (quoted)
• npm/npx via NVM: ensure NVM loaded in execution context

Got: Platform-specific issue identified (Windows arg parsing, WSL path resolution, NVM context loading).

If fail: Windows-specific? Switch from command-line args to env vars for auth. WSL-specific? Verify Windows executable path accessible from WSL via /mnt/c/....

Step 7: Reset and Reconfigure

If all else fails:

# Remove and re-add the server (Claude Code)
claude mcp remove server-name
claude mcp add server-name stdio "/full/path/to/executable" -- args

# Restart Claude Desktop after config changes
# (close and reopen the application)

Got: After remove and re-add, claude mcp list shows server with correct config. Fresh connection succeeds.

If fail: Re-add fails? Check executable path correct. Run command directly in terminal — works? For Claude Desktop, ensure app fully closed (check system tray) before restart.

Step 8: Check Logs

Claude Code: Look for MCP errors in terminal output when start session.

Claude Desktop: Check application logs (location varies by OS).

Server-side: Add logging to MCP server. Capture incoming requests, errors.

Got: Log entries reveal specific failure point (server startup, handshake, auth, tool registration).

If fail: No logs? Add stderr capture to server command (redirect to log file). Reproduce failure. For Claude Desktop, check %APPDATA%\Claude\logs\ for app-level logs.

Checks

• Server starts independent, no errors
• Config JSON valid
• Client connects
• MCP tools appear in session
• Tools execute when called
• Connection persists across multiple requests

Pitfalls

• Edit wrong config file: Claude Code (~/.claude.json) vs Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json)
• No restart after config change: Claude Desktop needs restart. Claude Code picks up changes on new session
• npx in restricted env: npx downloads packages at runtime. Network or permissions restricted? Install global
• Token expiration: Hugging Face tokens expire. Regenerate if auth fails appear sudden
• Version mismatch: MCP protocol versions must be compatible — client, server

See Also

• configure-mcp-server - initial MCP setup
• build-custom-mcp-server - custom server debugging context
• setup-wsl-dev-environment - WSL prerequisite setup

Source: pjt222/agent-almanac — distributed by TomeVault.