Troubleshooting¶

Solutions to common issues.

Common Issues¶

Server Won't Start¶

Symptom:

Error: connection refused

Solutions:

Check port availability:
```
lsof -i :8080
```

Verify MCP server command:

npx @modelcontextprotocol/server-filesystem ./  # Test standalone

Check logs:

leanproxy-mcp server run --verbose --stdio

Server Disconnects or Stops Responding¶

Symptom: An MCP server (e.g. garmin) stops responding mid-session. Tool calls hang or return "request timed out", and the only known fix used to be disconnecting/reconnecting the MCP in the client.

Why this happened: Two bugs compounded each other:

A freshly started stdio server was stopped almost immediately because its "last request" timestamp was never initialized — the idle timer fired on the first tick (~30s after startup) and shut the process down.
When a stdio server was stopped and then restarted, the new process never got a working request loop, so it accepted connections but never answered — requests hung until timeout.

Current behavior (auto-recovery):

With auto-reconnect enabled (default), LeanProxy-MCP now handles these cases automatically:

Crash recovery: if a stdio process exits unexpectedly it is respawned with exponential backoff, and the restart budget resets after a server stays up for stable_window.
Liveness probe: idle/running servers are pinged every health_check_interval; health_check_failures consecutive failures trigger a restart. Pings are MCP pings and do not consume AI tokens.
Transport recovery: http/sse servers reconnect transparently when the connection drops, and the next tool call re-establishes a dead session.
Request retry: if a request lands on a server that is recovering, it waits briefly for the restart to finish instead of failing permanently. For http/sse, a request that fails on a genuine transport error is retried once after the reconnect.

If a server still appears stuck:

Check the logs for restart activity:

leanproxy-mcp server run --stdio --log-level debug --log-file /tmp/leanproxy.log
# Look for "auto-reconnect", "reconnect", "restart", "crash"
tail -f /tmp/leanproxy.log | grep -i "reconnect\|restart\|crash\|error"

Confirm the server binary works standalone:
```
garmin-mcp stdio
```
Tune the recovery knobs if the defaults are too aggressive or too slow (see Auto-Reconnect configuration).
As a last resort, disable auto-reconnect if it is interfering with a specific server:
```
reconnect:
  enabled: false
```

Redaction Not Working¶

Symptom: Sensitive data still appears in LLM input.

Solutions:

Verify redaction is enabled:
```
leanproxy-mcp context show
```

Add custom pattern:

redaction:
  enabled: true
  patterns:
    - name: "custom-secret"
      pattern: "MY_SECRET=[A-Z0-9]+"

Check pattern syntax:
```
leanproxy-mcp doctor
```

High Token Usage¶

Symptom: Token usage not decreasing.

Solutions:

Run in dry-run mode to see what's being redacted:
```
leanproxy-mcp server run --dry-run --stdio
```

Generate report:

leanproxy-mcp report --output report.md

Enable debug logging:

leanproxy-mcp server run --debug --stdio

IDE Connection Issues¶

Symptom: IDE cannot connect to LeanProxy-MCP.

Solutions:

Verify installation:
```
leanproxy-mcp version
```

Check IDE configuration:

{
  "mcpServers": {
    "leanproxy": {
      "command": "leanproxy-mcp",
      "args": ["server", "run", "--stdio"]
    }
  }
}

Restart IDE

Configuration Not Loading¶

Symptom: Config changes have no effect.

Solutions:

Check config file location:

echo $LEANPROXY_CONFIG
# or default:
~/.config/leanproxy/config.yaml

Validate config:
```
leanproxy-mcp context validate
```

Use explicit config:

leanproxy-mcp server run --config /path/to/config.yaml --stdio

Cache Issues¶

Cache Empty After List Tools¶

Symptom: list_tools returns no results or tools are not cached.

Solutions:

Check cache location:

leanproxy-mcp cache --location
ls -la ~/.config/leanproxy/toolcache/

Verify list_tools method works:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_tools","arguments":{"server_name":"garmin"}}}\n' | leanproxy-mcp server run --stdio

Check logs for errors:

leanproxy-mcp server run --stdio --log-level debug --log-file /tmp/leanproxy.log
# Then list tools in another terminal
tail -f /tmp/leanproxy.log | grep -i "list_tools\|cache\|error"

Clear and rebuild cache:

leanproxy-mcp cache --clear --server garmin
leanproxy-mcp cache --clear --server Intervals_icu
# Then search again to rebuild cache

Cache Not Persisting¶

Symptom: Cache files exist but are empty or disappear after restart.

Solutions:

Check directory permissions:

ls -la ~/.config/leanproxy/
chmod 755 ~/.config/leanproxy/toolcache/

Verify disk space:
```
df -h ~/.config/leanproxy/
```

Status File Issues¶

status --running Shows "No running leanproxy instance found"¶

Symptom: Running leanproxy but leanproxy status --running shows no instances.

Solutions:

Check if status file exists:

/bin/cat ~/.config/leanproxy/status/current.json

Verify you're running a recent version:

leanproxy-mcp version
# Should show version with status file support

Check if the running instance created the status file:

ls -la ~/.config/leanproxy/status/
# Should show current.json with recent timestamp

For stdio mode (OpenCode), ensure the binary is updated:

which leanproxy-mcp
# Verify it's the built binary, not an old version
go build -o /usr/local/bin/leanproxy-mcp .

Status File Not Updated¶

Symptom: Status file exists but shows stale data.

Solutions:

Kill old processes:

/bin/ps aux | grep leanproxy
kill <PID>  # Kill any running instances

Restart and verify:

# Start fresh instance
leanproxy-mcp server run --stdio &
# Wait a few seconds
leanproxy-mcp status --running

Debug Mode¶

Enable debug logging for troubleshooting:

leanproxy-mcp server run --stdio --log-level debug --log-file /tmp/leanproxy.log

Doctor Command¶

Run diagnostics:

leanproxy-mcp doctor

Checks: - Configuration syntax - Network connectivity - File permissions - Dependencies

Getting Help¶

GitHub Issues: https://github.com/mmornati/leanproxy-mcp/issues
Documentation: https://github.com/mmornati/leanproxy-mcp#readme