MCP-Server

Der MCP-Server unter mcp.diebrocks.com ist der zentrale externe MCP-Endpunkt für die Heimnetz-Infrastruktur und Home Assistant. Externe KI-Clients benötigen nur diese eine Verbindung.

Aktueller Stand 08.09.2026: modularer MCP-v4-Aufbau, unprivilegierter Hauptprozess, fail-closed Tool-Policy, gehärtete Befehlsausführung, Wiki-Härtung, minimiertes Audit-v2 mit root-eigenem Writer und interne Home-Assistant-Bridge.

Verbindliche Arbeitsregeln: MCP-Arbeitsregeln.
Neuinstallation: MCP-Server – Neuinstallation.
Home Assistant: Home Assistant Bridge.

Architektur

flowchart TD
    KI["KI-Client<br/>Claude · ChatGPT · andere MCP-Clients"]
    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"]
    TOOLS["29 Infrastruktur-, Datei-, Wiki-, System- und MikroTik-Tools"]
    HAB["5 HA-Bridge-Tools"]
    SSH["SSH → bekannte Infrastrukturziele"]
    WIKI["Git → Smart-Home-Wiki"]
    HAMCP["Home Assistant MCP Server<br/>10.10.10.20:9583"]
    HA["Home Assistant"]
    SOCKET["Audit-v2<br/>/run/mcp-audit-writer/audit.sock"]
    WRITER["mcp-audit-writer<br/>root"]
    LOGS["/var/log/mcp-audit/"]

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

Container

Eigenschaft	Wert
Container-ID	108
Hostname	mcp-server
IP	10.10.10.33
OS	Debian 13
MCP	Port 3000, Prozessbenutzer mcp
Admin	Port 3001, Prozessbenutzer root
Audit-Writer	lokaler root-Dienst über Unix-Socket
Autostart	Proxmox sowie mcp-audit-writer, mcp-shell, mcp-admin

Benutzerkonvention

Rolle	Benutzer	Einsatz
MCP-Prozess	mcp	CT 108, ohne sudo
Linux-Remotezugriff	mcp-agent	Proxmox und Linux-Container
MikroTik	mcp	eingeschränkter RouterOS-Benutzer
Home Assistant	ssh	Advanced SSH & Web Terminal

Der mcp-agent-Key ist mit no-port-forwarding,no-agent-forwarding,no-X11-forwarding eingeschränkt. Alte root-SSH-Schlüssel des MCP-Servers sind entfernt.

Sicherheitsmodell

Root-geschütztes Gate

shell_execute ist die Wartungsfreigabe für tiefere Arbeiten. Der MCP-Prozess selbst kann das Gate nicht verändern:

• /opt/mcp-shell/ und /opt/mcp-admin/ sind root-owned;
• mcp hat kein sudo auf CT 108;
• mcp-agent besitzt auf Proxmox nur die erlaubten Wrapper;
• tool-config.json wird fail closed geprüft;
• eine fehlende oder ungültige Policy führt nicht zu Standardfreigaben.

Rechte nach Ziel

Ziel	Zugriff
Proxmox	mcp-agent, nur mcp-pct und mcp-maintenance per sudo
CT 102/106/107	mcp-agent, bei freigegebener Shell-Wartung sudo möglich
CT 108	lokal mcp / SSH mcp-agent, niemals sudo
Home Assistant	Benutzer ssh
MikroTik	eingeschränkter Benutzer mcp

Weitere Schutzschichten

• write_file verwendet eine Pfad-Allowlist und zusätzliche Hard-Denies.
• disabled_tools wird über die gemeinsame Policy-Schicht ausgewertet.
• Wiki-Git-Operationen laufen ohne Shell-String-Verkettung über lib/wiki-safe.js.
• Prozessfehler, Exitcodes, Zeitlimits und SSH-Fehler werden strukturiert statt als scheinbare Erfolgstexte zurückgegeben.
• Audit-Inhalte werden vor dem Schreiben auf ein festes Audit-v2-Schema reduziert.
• Der Benutzer mcp kann vorhandene Audit-Dateien nicht direkt verändern oder löschen.
• HA-Bridge-Aufrufe speichern im äußeren Audit keine HA-Argumente oder HA-Antworten.

Details:

• Tool-Freigaben
• Audit-Inhalte begrenzen
• Audit-Integrität
• Befehlsfehler und Exitcodes
• Admin-Oberfläche

Bekannte Hosts

Host	IP	SSH-User	ID/Zweck
proxmox	10.10.10.10	mcp-agent	Hypervisor
cloudflared	10.10.10.30	mcp-agent	CT 102
ebusd-heizung	10.10.10.31	mcp-agent	CT 106
ebusd-lueftung	10.10.10.32	mcp-agent	CT 107
mcp-server	10.10.10.33	mcp-agent	CT 108
home-assistant	10.10.10.20	ssh	HAOS VM 101
mikrotik	10.10.10.1	mcp	Router

Die SSH-Host-Schlüssel liegen unter /home/mcp/.ssh/known_hosts. Host-Key-Prüfung nicht pauschal deaktivieren; bei Änderungen den neuen Schlüssel bewusst prüfen.

Tool-Oberfläche

Der äußere MCP stellt aktuell 34 sichtbare Tools bereit:

• 29 normale Infrastruktur-, Datei-, Wiki-, System- und MikroTik-Tools;
• 5 Home-Assistant-Bridge-Tools.

HA-Bridge

ha_search_tools
ha_call_read_tool
ha_call_write_tool
ha_call_delete_tool
ha_get_skill_guide

Die vollständigen HA-MCP-Werkzeuge werden dynamisch über ha_search_tools gefunden. Dadurch muss der äußere MCP den großen HA-Toolkatalog nicht statisch spiegeln.

Read-, Write- und Delete-Proxys erzwingen die jeweilige Toolklasse. Falsch geroutete Aufrufe werden abgewiesen.

Audit

flowchart LR
    MCP["mcp-shell"] -->|Audit-v2| 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, 0750;
• Tagesdateien: root:mcp, 0640;
• 7 Tage Aufbewahrung.

Das Audit speichert nur profilierte beziehungsweise minimierte Metadaten. Freie Befehle, Datei-/Wiki-Inhalte und HA-Antworten werden nicht ungefiltert übernommen.

HA-Bridge-Aufrufe wurden produktiv mit korrekter Zuordnung Enrico / OpenAI MCP einschließlich IP und cf_ray geprüft. Die eigentliche Home-Assistant-Aktion wird zusätzlich im HA-MCP-eigenen Audit protokolliert.

Dateien

/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

/opt/mcp-audit-writer/
└── audit-writer.js

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

/opt/wiki/
/home/mcp/wiki-backups/
/var/log/mcp-audit/

Die HA-MCP-Umgebungsdatei ist root-eigen mit Modus 0600. Der darin enthaltene Secret-Pfad wird nicht dokumentiert.

Systemd

Produktiv relevant:

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

Der HA-Upstream wird über den Drop-in 30-ha-upstream.conf in mcp-shell eingebunden.

Statusprüfung auf Proxmox:

pct exec 108 -- systemctl status mcp-audit-writer mcp-shell mcp-admin --no-pager

Admin-Oberfläche

• URL: https://mcp.diebrocks.com/admin
• läuft als root auf Port 3001;
• durch Cloudflare Access geschützt;
• verwaltet Shell-Gate, Tool-Freigaben, Policy, Audit-Anzeige und MCP-Neustart.

Cloudflare

Tunnel-Ingress:

mcp.diebrocks.com/admin* → 10.10.10.33:3001
mcp.diebrocks.com/*      → 10.10.10.33:3000

MCP-Clients verwenden Streamable HTTP unter:

https://mcp.diebrocks.com/mcp

Die Cloudflare-Access-Zugangsdaten gehören nicht ins Wiki.

Wartung und Änderungen

Produktiver Code ist root-geschützt. Änderungen werden in einem beschreibbaren Staging-Bereich vorbereitet und geprüft. Die Installation startet der Mensch anschließend als root auf Proxmox beziehungsweise CT 108.

Vor einem Deployment:

1. Ausgangsdateien und Prüfsummen prüfen;
2. Backup anlegen;
3. Tests und Syntaxprüfung ausführen;
4. nur die vorgesehenen Dateien austauschen;
5. Dienste neu starten;
6. echte MCP-Aufrufe durchführen;
7. Audit prüfen;
8. Wiki im selben Arbeitsgang aktualisieren.

Nach Wartungsarbeiten die Shell-Freigabe über die Admin-Oberfläche wieder deaktivieren, wenn sie nicht dauerhaft benötigt wird.

Historie

Datum	Maßnahme
08.09.2026	Home-Assistant-Bridge produktiv ergänzt: fünf Gateway-Tools, interner HA-MCP-Upstream, getrennte Read/Write/Delete-Proxys, minimiertes Gateway-Audit und korrekte Caller-Zuordnung durch R5.
08.09.2026	Audit-Integrität auf root-eigenen Writer und Tagesdateien umgestellt.
08.09.2026	Audit-v2-Inhaltsbegrenzung, fail-closed Tool-Policy, Wiki-Härtung, Admin-Oberfläche und strukturierte Befehlsfehler produktiv installiert.
10.08.2026	MCP v4 mit modularer Registry und damals 29 Tools produktiv eingeführt.
Juli 2026	MCP-Prozess auf unprivilegierten Benutzer mcp umgestellt; alte root-SSH-Schlüssel entfernt.