Zum Inhalt

Homelab MCP – Admin-Dienst

Stand 09.09.2026: Der neue homelab-mcp besitzt auf CT 109 einen eigenen lokalen Admin-Dienst. Die Anwendung selbst läuft weiterhin ausschließlich auf Loopback. Für den geplanten Zugriff über mcp2.diebrocks.com existiert davor ein separater, auf den Cloudflared-LXC begrenzter Ingress-Proxy.

Ziel

Nach der Erstinstallation soll die normale Administration nicht mehr über Shell-Dateibearbeitung erfolgen, sondern über die strukturierte Admin-Oberfläche.

Der Kontrollpfad ist vom MCP-Datenpfad getrennt:

flowchart LR
    UI["Admin UI"] --> HTTP["127.0.0.1:3001"]
    HTTP --> API["Admin API"]
    API --> AUTH["Session + CSRF"]
    API --> CFG["Konfiguration"]
    API --> SEC["Secrets"]
    API --> POLICY["Plugin-/Tool-Policy"]
    API --> AUDIT["Audit"]

    MCP["homelab-mcp.service\nUser homelab-mcp"]
    ADMIN["homelab-mcp-admin.service\nUser root · Group homelab-mcp"]

Der eigentliche MCP-Dienst bleibt unprivilegiert. Root-Rechte liegen nur im separaten Admin-Kontrollpfad und im Audit-Writer.

Systemd-Dienst

Dienst:

homelab-mcp-admin.service

Wichtige Eigenschaften:

User=root
Group=homelab-mcp
HOMELAB_MCP_ADMIN_HOST=127.0.0.1
HOMELAB_MCP_ADMIN_PORT=3001
Requires=homelab-mcp-audit-writer.service

Härtung unter anderem:

NoNewPrivileges=yes
PrivateTmp=yes
PrivateDevices=yes
ProtectSystem=strict
ProtectHome=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectControlGroups=yes
ProtectClock=yes
ProtectHostname=yes
RestrictSUIDSGID=yes
RestrictRealtime=yes
RestrictNamespaces=yes
LockPersonality=yes
CapabilityBoundingSet=
AmbientCapabilities=
ReadWritePaths=/etc/homelab-mcp

Der Admin-Prozess darf damit die geschützte lokale Konfiguration und Secrets ändern, hat aber keinen allgemeinen beschreibbaren Systembereich.

Erreichbarkeit

Lokal auf CT 109:

http://127.0.0.1:3001/admin/

API-Status:

http://127.0.0.1:3001/api/auth/status

Der Dienst wurde zusätzlich von CT 108 aus direkt gegen 10.10.10.50:3001 geprüft. Eine direkte Verbindung ist nicht möglich, weil der Dienst nur an 127.0.0.1 gebunden ist.

Aktueller Auth-Status

Das Initialpasswort ist seit dem 09.09.2026 gesetzt. Gespeichert wird ausschließlich der scrypt-Hash unter:

/etc/homelab-mcp/secrets/admin-password-hash

Der Klartext wurde weder im Wiki noch in der MCP-Konfiguration hinterlegt.

Erstpasswort

Das erste Admin-Passwort kann absichtlich nicht über eine unauthentifizierte HTTP-Route gesetzt werden.

Der Bootstrap erfolgt einmalig lokal als root über:

node /opt/homelab-mcp/current/src/admin/bootstrap-password.js

Das Passwort wird über stdin übergeben und darf nicht direkt als Kommandozeilenargument verwendet werden.

Anforderungen:

  • mindestens 12 Zeichen;
  • nur einmaliger Initial-Bootstrap;
  • Speicherung ausschließlich als scrypt-Hash;
  • vorhandene Sessions werden beim Setzen beziehungsweise Ändern verworfen;
  • der Bootstrap selbst wird über den privileggetrennten Audit-Pfad mit attempt und success/error protokolliert;
  • der Klartextwert wird nicht ins Audit übernommen.

Authentifizierung

Nach gesetztem Passwort verwendet die Admin-Oberfläche:

  • scrypt-Passwort-Hashing;
  • zufällige Session-Tokens;
  • zufällige CSRF-Tokens;
  • standardmäßig 30 Minuten Session-Laufzeit;
  • begrenzte maximale Session-Anzahl;
  • HttpOnly-Session-Cookie;
  • SameSite=Strict;
  • CSRF-Pflicht für Mutationen;
  • Login-Rate-Limit;
  • Host- und Origin-Prüfung;
  • Request-Größenlimit;
  • kein CORS.

Für den geplanten Zugriff über https://mcp2.diebrocks.com ist das Session-Cookie inzwischen wieder mit Secure konfiguriert. Die Admin-Anwendung bleibt auf 127.0.0.1:3001. Davor läuft der separate Dienst:

homelab-mcp-admin-ingress.service

Lokaler Ingress auf CT 109:

10.10.10.34:3101 -> 127.0.0.1:3001

Der Ingress akzeptiert ausschließlich die Quelladresse des Cloudflared-LXC 10.10.10.30. Ein Live-Test vom Cloudflared-LXC lieferte HTTP 200; ein Zugriff aus einer anderen internen Quelle wurde mit HTTP 403 abgewiesen. Der bestehende produktive Host mcp.diebrocks.com bleibt davon vollständig getrennt und unverändert.

Bereits vorhandene Admin-Funktionen

Die API/UI kann bereits:

  • Sicherheitsstatus anzeigen;
  • Plugins anzeigen sowie aktivieren/deaktivieren;
  • Policy nach read, write, destructive verwalten;
  • einzelne Tools explizit erlauben oder sperren;
  • Secrets auflisten, anlegen/ersetzen und löschen, ohne Secret-Werte zurückzugeben;
  • validierte Konfiguration anzeigen;
  • Audit-Ereignisse anzeigen;
  • Admin-Passwort ändern;
  • Session abmelden.

Proxmox in der Admin-Ebene

Der Admin-Dienst lädt dieselbe interne SSH-Capability wie der MCP-Dienst. Dadurch erkennt er das Proxmox-Plugin auf CT 109 als technisch bereit.

Aktuelle Policy:

proxmox.read=true
proxmox.write=false
proxmox.destructive=false

Die vorbereiteten Proxmox-Tools start, stop und restart bleiben dadurch gesperrt.

Automatischer MCP-Reload

Der MCP-Dienst überwacht das Verzeichnis seiner config.json und lädt den Tool-Katalog automatisch neu, wenn die Konfiguration atomar ersetzt wird.

Das passt zum ConfigStore, der Änderungen sicher per Temp-Datei plus Rename schreibt. Plugin- und Policy-Änderungen aus der Admin-Ebene benötigen deshalb keinen Neustart des MCP-Dienstes.

Der Live-Test auf CT 109 wurde am 08.09.2026 erfolgreich durchgeführt:

  1. ursprüngliche config.json gesichert und aktuelle MCP-PID notiert;
  2. system atomar auf enabled=false gesetzt;
  3. ohne Dienstneustart über den offiziellen MCP-v2-Client tools/list abgefragt;
  4. system_status war verschwunden, die beiden read-only Proxmox-Tools blieben sichtbar;
  5. Originalkonfiguration atomar wiederhergestellt;
  6. MCP-PID war unverändert;
  7. erneutes tools/list zeigte wieder system_status sowie die beiden read-only Proxmox-Tools.

Damit ist der automatische Config-Reload nicht nur automatisiert, sondern auch auf dem laufenden CT 109 Ende-zu-Ende bestätigt.

Noch ausstehend

CT 109 ist für den neuen Hostnamen mcp2.diebrocks.com vorbereitet. Im Cloudflare-Tunnel fehlen noch die beiden additiven Regeln für mcp2.diebrocks.com: ^/(admin|api) auf http://10.10.10.34:3101 und der MCP-Fallback auf http://10.10.10.34:3100, außerdem die DNS-Route. Die bestehende Konfiguration für mcp.diebrocks.com darf dabei nicht verändert werden.

Danach folgen Login-, Session-, CSRF- sowie Update-/Release-Tests über den vorgesehenen HTTPS-Weg.