Feature Request: Document Preview MCP with remote backend pattern

Summary

When developing a frontend locally while the backend (API server + database) runs on a remote machine (home server, VM, cloud instance), the Preview MCP needs a reverse-proxy pattern to bridge the gap. This is a common setup for teams with shared dev servers, resource-constrained laptops, or multi-machine development environments.

Problem

The Preview MCP documentation assumes the full stack runs locally. In practice:

1. Resource-constrained machines (e.g. laptops with limited RAM/disk) may not run Docker + database locally
2. Shared backend infrastructure — the API server and DB often run on a dedicated machine
3. Vite 7.x + Node.js 24 has a known issue where the built-in http-proxy fails with IPv6-first DNS resolution, making the standard proxy config unreliable even for local backends

Solution Pattern

A lightweight reverse proxy (dev-proxy.mjs, ~70 lines using native node:http) that:

• Forwards /api/* and /ws to the remote backend
• Adds CORS headers for the local dev origin
• Uses explicit IPv4 addressing to avoid the Node.js 24 IPv6 issue
• Is configurable via GATEWAY_HOST environment variable

Architecture

Browser → Vite (5173) → dev-proxy (5174) → Remote Gateway (8080)
           ↑ HMR             ↑ API + WS         ↑ API server + DB
           local             local               remote machine

Integration with Preview MCP

The launch.json starts both proxy and Vite via a shell wrapper:

{
  "configurations": [{
    "name": "ui-dev",
    "runtimeExecutable": "bash",
    "runtimeArgs": ["packages/ui/dev-start.sh"],
    "port": 5173
  }]
}

The shell script:

#!/bin/bash
set -e
DIR="$(cd "$(dirname "$0")" && pwd)"
cd "$DIR"

cleanup() { kill $PROXY_PID $VITE_PID 2>/dev/null; wait 2>/dev/null; }
trap cleanup EXIT INT TERM

node dev-proxy.mjs &
PROXY_PID=$!

VITE_API_BASE=http://localhost:5174 npx vite --host 0.0.0.0 --port 5173 &
VITE_PID=$!

# POSIX `wait` — macOS ships bash 3.2, `wait -n` requires bash 4+
wait $PROXY_PID $VITE_PID

Additional Gotchas Discovered

| Issue | Detail |
|-------|--------|
| wait -n on macOS | macOS default bash is 3.2; wait -n requires 4+. Use POSIX wait |
| NODE_ENV=production in .env | Vite rejects this in dev mode — only development is supported in .env |
| launch.json absolute paths | Break when syncing configs between Linux/macOS. Use relative paths |
| Vite ignores PORT env | Only respects --port CLI flag or server.port in config |

Request

Consider adding a section to the Preview MCP documentation (or a cookbook/examples directory) covering:

1. The reverse-proxy pattern for remote backends
2. The launch.json shell wrapper approach for multi-process dev setups
3. Known platform-specific issues (macOS bash, Node.js 24 IPv6)

Happy to contribute a PR with documentation if there's interest.