MCP-Server — Neuinstallation und Wiederaufbau

Diese Seite beschreibt den aktuellen produktiven Aufbau mit Stand 08.09.2026. Sie dient für eine Neuinstallation von CT 108 beziehungsweise einen kontrollierten Wiederaufbau.

Architektur und laufendes System: MCP-Server
Home-Assistant-Anbindung: Home Assistant Bridge
Arbeitsregeln: MCP-Arbeitsregeln

Keine alten MCP-Stände wiederherstellen

Frühere Fassungen dieser Seite beschrieben einen monolithischen MCP, ein direkt vom Benutzer mcp beschreibbares Audit-Log und eine lockere SSH-Host-Key-Prüfung. Diese Varianten gehören nicht mehr zum produktiven Sicherheitsmodell.

Zielzustand

flowchart TD
    KI["Claude / ChatGPT / anderer MCP-Client"]
    CF["Cloudflare Access + Tunnel<br/>mcp.diebrocks.com"]
    MCP["/mcp → CT 108:3000<br/>mcp-shell · User mcp"]
    ADMIN["/admin → CT 108:3001<br/>mcp-admin · root"]
    NORMAL["Infrastruktur-, Wiki- und MikroTik-Tools"]
    HAB["5 Home-Assistant-Bridge-Tools"]
    HAMCP["Home Assistant MCP Server<br/>10.10.10.20:9583"]
    HA["Home Assistant"]
    SOCKET["Audit-v2 → Unix-Socket"]
    WRITER["mcp-audit-writer · root"]
    LOGS["/var/log/mcp-audit/"]

    KI -->|HTTPS + Cloudflare Access| CF
    CF --> MCP
    CF --> ADMIN
    MCP --> NORMAL
    MCP --> HAB
    HAB -->|internes LAN| HAMCP
    HAMCP --> HA
    MCP --> SOCKET
    SOCKET --> WRITER
    WRITER --> LOGS

Der einzige externe MCP-Endpunkt ist https://mcp.diebrocks.com/mcp. Home Assistant wird intern über den separat gepflegten HA-MCP-Server angebunden.

1. Voraussetzungen

• Proxmox und das Management-Netz sind verfügbar.
• Cloudflare Tunnel auf CT 102 funktioniert.
• Home Assistant ist unter 10.10.10.20 erreichbar.
• Das Smart-Home-Wiki-Repository ist verfügbar.
• Das geprüfte MCP-Recovery-Paket oder ein aktuelles vollständiges Backup von CT 108 ist verfügbar.

Wiki ist kein Quellcode-Backup

Die Dokumentation beschreibt Aufbau, Rechte und Wiederherstellung. Für einen Totalausfall von CT 108 muss der aktuelle Inhalt von /opt/mcp-shell/ und /opt/mcp-admin/ beziehungsweise ein vollständiges Deployment-Paket außerhalb des verlorenen Containers verfügbar sein. Die Rollback-Verzeichnisse unter /root/ helfen nur, solange CT 108 selbst noch vorhanden ist.

2. CT 108 anlegen

Beispiel auf Proxmox:

pct create 108 local:vztmpl/debian-13-standard_13.x_amd64.tar.zst \
  --hostname mcp-server \
  --unprivileged 1 \
  --features nesting=1 \
  --memory 512 \
  --swap 512 \
  --cores 1 \
  --rootfs local-lvm:8 \
  --net0 name=eth0,bridge=vmbr0,ip=10.10.10.33/24,gw=10.10.10.1 \
  --nameserver 10.10.10.1 \
  --start 1

Der Container verwendet 10.10.10.1 als DNS und diebrocks.home als Searchdomain. Autostart aktivieren.

3. Grundsystem

pct enter 108
apt-get update
apt-get upgrade -y
apt-get install -y curl git openssh-server ca-certificates
systemctl enable --now ssh

Node.js und npm installieren. Vor einem Wechsel auf einen neuen Node-Major-Release die MCP-Testpakete ausführen.

4. Benutzer

Der MCP läuft als unprivilegierter Benutzer mcp mit UID 999, primärer Gruppe mcp mit GID 991 und ohne sudo:

groupadd -g 991 mcp
useradd -m -u 999 -g mcp -s /bin/bash mcp
passwd -l mcp
mkdir -p /home/mcp/.ssh
chown mcp:mcp /home/mcp/.ssh
chmod 700 /home/mcp/.ssh

Zusätzlich existiert mcp-agent für die bekannten Linux-SSH-Ziele. Auf CT 108 erhält mcp-agent kein sudo.

5. SSH-Schlüssel und Host-Vertrauen

Als mcp getrennte Ed25519-Schlüssel für Infrastruktur und Wiki erzeugen:

su - mcp
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "mcp-remote" -N ""
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_wiki -C "mcp-wiki" -N ""
exit

Schlüssel	Verwendung
/home/mcp/.ssh/id_ed25519	Proxmox, Linux-Container, Home Assistant, MikroTik
/home/mcp/.ssh/id_ed25519_wiki	GitHub Deploy Key für das Wiki

Für GitHub wird ein Alias github-wiki mit StrictHostKeyChecking yes verwendet. Die benötigten Host-Schlüssel werden gezielt in /home/mcp/.ssh/known_hosts hinterlegt.

Warning

StrictHostKeyChecking no nicht verwenden. Ein geänderter Host-Key muss bewusst geprüft und anschließend gezielt ersetzt werden.

6. Zielsysteme vorbereiten

Proxmox

mcp-agent erhält nur sudo für die eingeschränkten Wrapper:

/usr/local/bin/mcp-pct
/usr/local/bin/mcp-maintenance

Kein allgemeines root/sudo auf dem Hypervisor.

Arbeits-Container 102 / 106 / 107

Der öffentliche Schlüssel wird für mcp-agent mit

no-port-forwarding,no-agent-forwarding,no-X11-forwarding

in authorized_keys eingetragen. Diese Arbeits-Container dürfen bei aktivierter Shell-Wartungsfreigabe sudo bereitstellen.

CT 108 selbst

mcp-agent erhält keinen sudoers-Eintrag. Dadurch kann der MCP sein eigenes Gate und den root-eigenen Produktivcode nicht über SSH umgehen.

Home Assistant

Der Infrastruktur-Schlüssel wird im Add-on Advanced SSH & Web Terminal für den Benutzer ssh hinterlegt.

MikroTik

Der RouterOS-Benutzer mcp bleibt eingeschränkt; keine Full-/Admin-Gruppe nur für den MCP vergeben.

7. Wrapper installieren

Auf Proxmox werden die geprüften produktiven Fassungen von mcp-pct und mcp-maintenance installiert. mcp-pct darf ausschließlich die vorgesehenen LXC-, systemd- und Journal-Aktionen ausführen.

Auf den Debian-Arbeitszielen wird mcp-maintenance für Paketprüfung, Upgrade und Cleanup verwendet.

Für einen Wiederaufbau die aktuellen Wrapper aus dem gesicherten Produktivstand übernehmen, nicht aus veralteten Chat-Snippets rekonstruieren.

8. MCP-v4-Code installieren

Der MCP ist modular aufgebaut. Der produktive Bestand umfasst mindestens:

/opt/mcp-shell/
├── index.js
├── tool-registry.js
├── tools/
├── lib/
│   ├── core.js
│   ├── command-runner.js
│   ├── audit-safe.js
│   ├── wiki-safe.js
│   ├── tool-policy.js
│   ├── ha-upstream.js
│   └── ha-preload.js
├── rules/
├── tool-config.json
├── package.json
└── node_modules/

/opt/mcp-admin/
├── server.js
├── policy-routes.js
├── policy-client.js
├── admin.html
├── admin.css
└── node_modules -> /opt/mcp-shell/node_modules

Aktuellen geprüften Produktivcode einspielen, Abhängigkeiten installieren und anschließend root-eigen machen:

cd /opt/mcp-shell
npm install
chown -R root:root /opt/mcp-shell /opt/mcp-admin

Vor dem Start JavaScript-Syntax prüfen. Eine Neuinstallation nur mit einem alten index.js ist unvollständig.

9. Tool-Policy und Shell-Gate

Die Policy liegt unter:

/opt/mcp-shell/tool-config.json

Sie wird durch lib/tool-policy.js strikt geprüft. Fehlende, unlesbare oder ungültige Konfiguration muss fail closed behandeln und darf keine stillschweigenden Standardfreigaben erzeugen.

Aktuelle Grundstruktur:

{
  "disabled_tools": [],
  "write_allow": {
    "ebusd-heizung": ["/etc/ebusd/", "/tmp/"],
    "ebusd-lueftung": ["/etc/ebusd/", "/tmp/"],
    "home-assistant": ["/config/", "/tmp/"],
    "mcp-server": ["/tmp/"],
    "proxmox": [],
    "cloudflared": []
  }
}

Details: Tool-Freigaben absichern.

shell_execute wird ausschließlich über das root-geschützte Gate beziehungsweise die Admin-Oberfläche freigegeben. Der MCP darf dieses Gate nicht selbst ändern.

10. Audit-v2 und Root-Writer

Das alte Einzel-Log /var/log/mcp-shell-audit.jsonl wird nicht verwendet.

flowchart LR
    TOOL["MCP-Tool-Aufruf"] --> SAFE["audit-safe.js<br/>Audit-v2-Projektion"]
    SAFE --> SOCKET["Unix-Socket<br/>/run/mcp-audit-writer/audit.sock"]
    SOCKET --> WRITER["mcp-audit-writer<br/>root"]
    WRITER --> LOG["/var/log/mcp-audit/<br/>YYYY-MM-DD.jsonl"]

Rechte:

• /var/log/mcp-audit/: root:mcp, Modus 0750;
• Tagesdateien: root:mcp, Modus 0640;
• Unix-Socket: für root:mcp, Modus 0660 vorgesehen;
• mcp darf Audit-Dateien lesen, aber nicht direkt schreiben, kürzen oder löschen.

Der Root-Writer akzeptiert nur das streng begrenzte Audit-v2-Schema. Die Allowlist muss neben den normalen Infrastruktur-Tools auch die fünf HA-Bridge-Tools enthalten:

ha_search_tools
ha_call_read_tool
ha_call_write_tool
ha_call_delete_tool
ha_get_skill_guide

Details: Audit-Inhalte begrenzen und Audit-Integrität.

11. Home-Assistant-Bridge

Home Assistant MCP bleibt ein eigenständiges HA-Add-on und wird unabhängig aktualisiert. Der zentrale MCP verbindet sich intern über das LAN mit ihm.

Produktive Dateien:

/opt/mcp-shell/lib/ha-upstream.js
/opt/mcp-shell/lib/ha-preload.js
/etc/mcp-shell/ha-upstream.env
/etc/systemd/system/mcp-shell.service.d/30-ha-upstream.conf

Die interne HA-MCP-URL einschließlich Secret-Pfad liegt ausschließlich in /etc/mcp-shell/ha-upstream.env, root-eigen mit Modus 0600. Den Secret-Pfad niemals ins Wiki übernehmen.

Der systemd-Drop-in lädt die Umgebungsdatei und den Node-Preload. R5 sorgt zusätzlich dafür, dass HA-Bridge-Aufrufe im äußeren Audit mit derselben Caller-Kategorisierung wie normale MCP-Aufrufe erscheinen. HA-Argumente und HA-Antworten werden dort nicht gespeichert.

Details und Rollback: Home Assistant Bridge.

12. Admin-Oberfläche

mcp-admin läuft als root auf Port 3001 und bleibt über Cloudflare Access geschützt. Die Oberfläche verwaltet insbesondere:

• Shell-Freigabe;
• Tool-Freigaben;
• Policy-Konfiguration;
• Audit-Anzeige;
• MCP-Neustart für Recovery.

Produktive Dateien aus dem gesicherten Stand übernehmen. Die Admin-Oberfläche darf die fail-closed Policy-Prüfung und die Audit-Härtung nicht umgehen.

13. systemd

Mindestens diese Dienste müssen vorhanden und aktiviert sein:

mcp-shell.service
mcp-admin.service
mcp-audit-writer.service

Zusätzlich gehört der Drop-in

/etc/systemd/system/mcp-shell.service.d/30-ha-upstream.conf

zum produktiven Aufbau.

Nach dem Einspielen:

systemctl daemon-reload
systemctl enable --now mcp-audit-writer mcp-shell mcp-admin
systemctl --no-pager --full status mcp-audit-writer mcp-shell mcp-admin

14. Wiki einrichten

Der Wiki-Key wird als GitHub Deploy Key mit Schreibrecht hinterlegt. Anschließend als mcp:

git clone github-wiki:HerrBausW/smarthome-wiki /opt/wiki

Das Wiki-Verzeichnis gehört mcp. Die produktiven Wiki-Tools verwenden lib/wiki-safe.js; Git-Aufrufe werden ohne Shell-String-Verkettung ausgeführt. Private Sicherungen vor Inhaltsersetzung/Löschung liegen unter /home/mcp/wiki-backups/.

15. Cloudflare

Tunnel-Ingress auf CT 102:

- hostname: mcp.diebrocks.com
  path: ^/admin
  service: http://10.10.10.33:3001

- hostname: mcp.diebrocks.com
  service: http://10.10.10.33:3000

Cloudflare Access schützt sowohl MCP als auch Admin. Der externe MCP-Client verwendet nur:

https://mcp.diebrocks.com/mcp

mit den vorgesehenen Cloudflare-Access-Dienstanmeldeinformationen.

16. Abschlussprüfung

Nach einer Neuinstallation mindestens prüfen:

1. mcp-audit-writer, mcp-shell und mcp-admin sind aktiv.
2. Unauthentifizierte Aufrufe auf MCP und Admin liefern 401.
3. Tool-Policy ist gültig und die gewünschte Sperrliste aktiv.
4. Normales Lese-Tool funktioniert und erzeugt einen minimierten Audit-v2-Eintrag.
5. shell_execute bleibt ohne menschliche Freigabe gesperrt.
6. Wiki-Lesen und -Schreiben funktionieren.
7. MikroTik- und Proxmox-Lesetools funktionieren.
8. ha_search_tools funktioniert über den zentralen MCP.
9. Ein harmloser ha_call_read_tool-Aufruf funktioniert.
10. Read-/Write-/Delete-Proxy-Trennung weist falsche Toolklassen ab.
11. HA-Bridge-Audit enthält Caller/Client und – sofern vom Request geliefert – IP und cf_ray, aber keine HA-Argumente oder Antworten.
12. Clients zeigen nach einem Neuverbinden insgesamt 29 normale plus 5 HA-Bridge-Tools.

Checkliste

• [ ] CT 108 mit korrektem Netz und Autostart angelegt
• [ ] Benutzer mcp und mcp-agent korrekt eingerichtet
• [ ] SSH-Schlüssel und known_hosts vorhanden
• [ ] Proxmox-/Wartungs-Wrapper installiert
• [ ] kompletter modularer MCP-v4-Code eingespielt
• [ ] tool-config.json und fail-closed Policy vorhanden
• [ ] Wiki-Härtung vorhanden
• [ ] Audit-v2-Projektion vorhanden
• [ ] mcp-audit-writer mit root-eigenen Tageslogs aktiv
• [ ] Admin-Oberfläche installiert
• [ ] HA-Bridge inklusive Secret-Environment und Preload installiert
• [ ] systemd-Drop-in für HA-Bridge vorhanden
• [ ] Cloudflare Access/Tunnel geprüft
• [ ] Wiki-Repo und Deploy Key eingerichtet
• [ ] Abschlussprüfung einschließlich HA-Bridge und Audit bestanden

Verwandte Dokumentation

• MCP-Server
• MCP-Recovery-Paket
• Home Assistant Bridge
• Tool-Freigaben
• Audit-Inhalte begrenzen
• Audit-Integrität
• Befehlsfehler und Exitcodes
• Admin-Oberfläche