Logging & Common Failures

Gemini CLI's MCP logging is sparse by default. Enable verbose logging with GEMINI_DEBUG=1 or GEMINI_LOG_LEVEL=debug to see the full JSON-RPC message exchange between Gemini and each server. The log reveals the exact sequence: initialize request, server capabilities response, tool listing, and then individual tool calls with their responses. When a server misbehaves, the log shows exactly where the conversation breaks down.

The five most common MCP failures in production: (1) Timeout on first connection — server takes too long to initialize, usually because it's connecting to a slow external service during startup. Fix: increase timeout or defer external connections to first tool call. (2) Tool not found — server exposes a tool but Gemini can't find it, usually because includeTools has a typo. Fix: run /tools and compare against server docs. (3) JSON parse error — server returns malformed JSON from a tool call. Fix: validate server output with the MCP Inspector. (4) Permission denied — server tries to access a resource the OS blocks. Fix: check file permissions and network access. (5) Server crash mid-session — the process dies and tools silently stop working. Fix: add process monitoring or use a server wrapper with auto-restart.

# Enable debug logging for MCP diagnostics
GEMINI_DEBUG=1 gemini 2>gemini-debug.log

# Filter MCP-specific messages
grep -i "mcp\|server\|tool" gemini-debug.log

# Common error patterns to search for:
# "timeout" — server initialization exceeded timeout
# "ECONNREFUSED" — server process not accepting connections
# "parse error" — malformed JSON-RPC response
# "tool not found" — includeTools mismatch or server capability gap
# "ENOENT" — command binary not found in PATH

# Monitor server processes during a session
ps aux | grep -E "server-github|server-postgres|mcp"