feat: auto-reconnect backends instead of 404ing forever when down

[FelixIsaac]

Problem

If a backend is unreachable when the proxy starts (and panicIfInvalid is false, the default), its route is never registered and the endpoint returns 404 page not found forever — the only fix is restarting the whole proxy.

Root cause is in startHTTPServer (http.go): the route is registered inside the per-backend goroutine, only after addToMCPServer succeeds:

errorGroup.Go(func() error {
    addErr := mcpClient.addToMCPServer(ctx, info, server.mcpServer)
    if addErr != nil {
        if panicIfInvalid { return addErr }
        return nil            // <- gives up; httpMux.Handle never runs
    }
    ...
    httpMux.Handle(mcpRoute, ...) // <- only reached on success
})

Two real-world cases this hurts:

1. Down at startup, comes up later — e.g. the proxy runs at login before an app that backs a streamable-http server is ready → route 404s permanently.
2. Was up, then dropped — the app/subprocess restarts; the existing ping task (client.go) detects the failure but only logs it, never reconnects.

I'd been working around both with an external watchdog that restarts the whole proxy on a timer; this fixes it in-process instead.

Changes

• Register the route up-front, before connecting. The handler resolves the live client lazily via a mutex-guarded getClient(), so the endpoint exists immediately and tools populate once the backend is reachable.
• Retry the initial connect in the background (connectWithRetry) until it succeeds, instead of giving up after one attempt.
• Reconnect on ping failure: rebuild the underlying client, re-initialize, and re-register tools/prompts/resources, swapping it in atomically. Transparent to in-flight/future requests since handlers go through getClient().
• Enable ping for stdio backends too, so a crashed subprocess is detected and respawned (stdio previously had no liveness check).
• Removed the now-unused errgroup usage.

New options (per-server, inheritable from mcpProxy.options)

Option	Type	Default	Meaning
autoReconnect	bool	true	Retry-at-startup + reconnect-on-drop. Set false to restore fail-once behaviour.
reconnectInterval	duration (ns)	15s	Gap between startup connection attempts.

panicIfInvalid still fails fast and takes precedence over autoReconnect.

Testing

Built and go vet clean. Verified end-to-end on Windows:

Down at startup (case 1): backend pointed at a closed port →

• GET /deadbackend/mcp returns 200 (route registered), not 404
• an unregistered route still 404s (control)
• logs show Connecting (attempt N) retrying at the configured interval

Drop + recovery (case 2): real @modelcontextprotocol/server-everything over stdio →

• connects, lists tools, serves traffic
• killed the server subprocess → MCP Ping failed: transport closed (count=1) → re-listed tools → Reconnected after 1 ping failure(s) within one ping cycle
• tools/call echo after reconnect returns Echo: alive-after-reconnect (new subprocess serving traffic)

Compatibility

Default behaviour change: backends now self-heal by default rather than failing once. Set autoReconnect: false to opt out. panicIfInvalid: true is unaffected.

[gemini-code-assist]

Code Review

This pull request introduces an auto-reconnect mechanism for MCP clients, allowing the proxy to register HTTP routes up-front and lazily resolve backend connections. It adds configuration options for AutoReconnect and ReconnectInterval, background connection retries, and mutex-based synchronization to safely swap connections on failure. The review feedback highlights potential nil pointer panics in client.go if c.options or opts is nil, suggesting safe defaults instead.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If c.options is nil (which can happen if the client is constructed directly or in tests without going through the config loader), accessing c.options.AutoReconnect will cause a nil pointer panic. We should check if c.options is nil before accessing its fields.

	autoReconnect := true
	if c.options != nil {
		autoReconnect = c.options.AutoReconnect.OrElse(true)
	}

[gemini-code-assist]

If opts is nil, accessing opts.ReconnectInterval, opts.AutoReconnect, or opts.PanicIfInvalid will cause a nil pointer panic. We should check if opts is nil and use safe defaults.

	gap := defaultReconnectGap
	autoReconnect := true
	panicIfInvalid := false
	if opts != nil {
		if opts.ReconnectInterval > 0 {
			gap = opts.ReconnectInterval
		}
		autoReconnect = opts.AutoReconnect.OrElse(true)
		panicIfInvalid = opts.PanicIfInvalid.OrElse(false)
	}

	attempt := 0
	for {
		attempt++
		log.Printf("<%s> Connecting (attempt %d)", c.name, attempt)
		err := c.addToMCPServer(ctx, info, mcpServer)
		if err == nil {
			log.Printf("<%s> Connected", c.name)
			return
		}
		log.Printf("<%s> Failed to connect: %v", c.name, err)
		if panicIfInvalid {