Connection Diagnostics

MCP server failures fall into three categories: startup failures (server process won't launch), connection failures (process starts but cannot establish the JSON-RPC channel), and runtime failures (server runs but tools produce errors). Each category has a different diagnostic approach. Startup failures are usually path issues — the command binary doesn't exist, npx can't resolve the package, or the Node.js version is incompatible. Connection failures are protocol issues — the server speaks a different MCP version, or stdin/stdout is corrupted by debug logging.

The first diagnostic step is always: can you run the server command manually? Copy the command and args from settings.json, paste into your terminal, and run it directly. If it fails there, the issue is with the server itself — not with Gemini CLI's configuration. If it runs manually but fails under Gemini, the issue is environment-related: missing env vars, different PATH, or permission restrictions.

# Step 1: Verify the server runs standalone
npx -y @modelcontextprotocol/server-github
# Should output JSON-RPC initialization messages to stderr
# Should NOT output anything to stdout (stdout is the MCP channel)

# Step 2: Check the Gemini CLI debug log
GEMINI_DEBUG=1 gemini
# Look for lines containing "mcp" — connection attempts, timeouts, errors

# Step 3: Test with MCP Inspector
npx @modelcontextprotocol/inspector \
  npx -y @modelcontextprotocol/server-github
# Opens a browser UI showing tools, resources, and real-time messages

# Step 4: Verify environment variables are set
env | grep -E "GITHUB_TOKEN|DATABASE_URL|API_KEY"
# Missing values = server will fail with cryptic errors