# Remote Diagnostics Setup (read-only) This guide explains how to let Claude Code run **read-only** diagnostics against a Multi-Hoster-Uploader instance running on a remote Windows server, through the local **stdio MCP gateway** in `gateway/`. The gateway is an MCP server to Claude and a WebSocket client to a diagnostic agent inside the app. It never touches the screen, never injects input, and never writes anything on the server. --- ## 1. Enable diagnostics on the server and copy the code On the **server** (the machine running the app): 1. Open the app's **Settings**. 2. Enable **"Diagnose-Zugriff"**. 3. Copy the connection **code**. It looks like `mhu1_`. The code carries the **host**, **port** and a one-time auth **token** (`mhu1_`). The bridge dials the host from the code, so you usually just hand over the code. Treat the code as a **secret**: anyone with the code and network reach to the agent can read diagnostics. **Two visibility modes** (Settings → Diagnose-Zugriff → Sichtbarkeit): - **Nur lokal** (default): the agent binds to `127.0.0.1`. Reach it through a tunnel (next step). - **Im Netzwerk**: the agent binds to `0.0.0.0` but is gated by a **fail-closed IP allowlist** — only source IPs/CIDRs you list may connect (loopback is always allowed), *in addition to* the token. An empty allowlist means loopback only. This is the mode to use with **Tailscale**: set the allowlist to your tailnet (e.g. `100.64.0.0/10`) and put the server's Tailscale IP / MagicDNS name into the code address — then the bridge connects straight over the tailnet, no SSH forward needed. **Transport note:** the agent speaks **plaintext `ws://`**. The token and the diagnostic data are *not* encrypted on the wire by the agent itself — confidentiality comes from the **tunnel** (Tailscale/WireGuard/SSH) you reach it through. In network mode the IP allowlist + token are the access gate; **only bind to the network behind a private tunnel you trust** (a tailnet, a VPN, or a trusted LAN). (A future build may add `wss`/TLS with cert pinning via an `fp` field in the code; it is not active today.) --- ## 2. Reach the agent over a tunnel The agent's default port is `9110`. Pick the path that matches your setup. ### Tailscale (recommended for many servers) Put every server and your gateway machine on the same tailnet. On each server, set **Sichtbarkeit = Im Netzwerk**, allowlist your tailnet (`100.64.0.0/10`, or the specific Tailscale IPs you'll connect from), and set the **code address** to that server's Tailscale IP or MagicDNS name. The bridge then connects straight to `:9110` — WireGuard (Tailscale) encrypts the transport, and the allowlist + token gate access. No SSH forward, no per-session tunnel command. ### SSH local port-forward (keep the agent loopback-only) With **Sichtbarkeit = Nur lokal**: ``` ssh -L 9110:127.0.0.1:9110 user@server ``` Leave that session open. Now `127.0.0.1:9110` on **your** machine is forwarded to the server's loopback. The code address is `127.0.0.1` (your local end of the tunnel). ### WireGuard (manual, alternative) Bring up a WireGuard tunnel and either bind the agent to the network with the peer's WG IP in the allowlist, or forward loopback over the tunnel and connect to `127.0.0.1`. > In **Nur lokal** mode the agent is unreachable except through a tunnel to loopback. In **Im > Netzwerk** mode the fail-closed IP allowlist (plus the token) is the access gate — only bind to > the network behind a tunnel/VPN you trust (a tailnet, WireGuard, or a trusted LAN). The transport > is plaintext; the tunnel is what encrypts it. --- ## 3. Install the gateway and register it with Claude (one time) On the machine running Claude Code: ``` cd gateway npm install ``` Register the gateway as an MCP server (one time): ``` claude mcp add --transport stdio mhu-diag -- node "C:\Users\ploet\Desktop\Claude Projekte\multi-hoster-uploader\gateway\index.js" ``` Adjust the absolute path if your checkout lives elsewhere. --- ## 4. Usage With the tunnel up, tell Claude: ``` server prod-3 at 127.0.0.1, code mhu1_<...> ``` Claude will: 1. call `connect_server(code:"mhu1_...", host:"127.0.0.1")`, 2. immediately read the app version via `get_system_info`, 3. remember the server under its label in `registry.json`. Next time you can just say: ``` connect_server(label:"prod-3") ``` with no code — the gateway dials it from the registry. Then ask Claude "what's wrong?" — it will typically start with **`server_health`**, the one-shot hub that aggregates errors, queue, rotation and system info in a single call. Other read-only tools: `read_log`, `list_logs`, `list_errors`, `get_queue_state`, `get_history`, `get_config_redacted`, `get_rotation_state`, `get_app_events`. --- ## 5. Failure → meaning When a connect or a request fails, the gateway returns a human-readable cause. Quick reference: | Symptom / signal | What it means / what to do | | -------------------------------------- | ----------------------------------------------------------------------- | | `ECONNREFUSED` | app not running / wrong port / inbound firewall closed | | `ETIMEDOUT` | firewall DROP / NAT not forwarded / tunnel down | | close code **4001** | auth timeout, retry | | close code **4002** | stale or rotated code — re-copy the current code from the server | | close code **4003** | brute-force lockout, wait 60s | | connected but no `auth-ok` | old app version without the diagnostic agent — update that server | | wss fingerprint mismatch | reserved for the future TLS mode (not active today) — re-copy the code | If you tunnel and still get `ECONNREFUSED`, check that the SSH session is up and that the agent is actually listening on `127.0.0.1:9110` on the server (Diagnose-Zugriff enabled). --- ## 6. What this is — and is not - It is **READ-ONLY**. It reads logs, errors, queue/history, redacted config, rotation and system info. **No screen capture. No input injection. No writes or config changes.** - The **code is a secret** (it carries the auth token). Don't paste it into public channels. - `gateway/registry.json` stores tokens for remembered servers and is **git-ignored** — never commit it.