# MCP-Host-Policy — wo Hosts herkommen

> **Grundsatz:** MCP-Endpoints (URLs, Hosts, IPs) werden **nicht** in `~/.claude.json` oder `~/.config/opencode/opencode.jsonc` hartcodiert. Sie kommen aus dem **Repo** (FQDN→Backend im `caddy/Caddyfile`, IP→Stack in `docs/nas-vlan20/stacks/*.yml`) oder werden **live über Portainer-API** verifiziert (`/api/endpoints/<id>/docker/containers/json?all=1`). In der Übergangszeit (GC rendert noch keine MCP-Liste) werden Hosts **manuell** in den genannten Configs gepflegt — aber **immer** mit Verweis auf diese Datei und das `bf-infra`-Repo.

## Hosts, die als "localhost" laufen

Bestimmte MCP-Dienste werden auf mehreren Hosts **gleichzeitig** lokal betrieben. In der MCP-Config steht dann **nicht** eine spezifische IP, sondern `localhost` (127.0.0.1) — und jeder Host, auf dem der MCP läuft, hat seine **eigene** Config.

| Dienst | Hosts | Begründung |
|---|---|---|
| **ollama** | **macmini** (`10.40.20.167`, BF-LAN), **meine Kiste / MacBook** (lokal) | Ollama läuft **auf jedem Host, der sie braucht** — der MCP-Client ist auch auf diesem Host, also reicht `http://localhost:11434`. Wer BF-LAN-Remote will: `export OLLAMA_HOST=http://10.40.20.167:11434` in der Shell. **Niemals** in der MCP-Config hartcodieren — der zweite Host (z.B. ein LXC, ein dritter Mac) wäre dann ausgeschlossen. |

## Hosts, die aus dem Repo (FQDN→Backend) kommen

`caddy/Caddyfile` ist SSoT für die **FQDN→Backend-IP-Port**-Tabelle (Stand 2026-08-28):

| Dienst | FQDN | Backend (`caddy/Caddyfile`) | Container (Portainer Endpoint 20 = macmini) |
|---|---|---|---|
| gitea-mcp | `gitea-mcp.emsenhuber.net` | `10.40.20.167:3000` | `gitea-mcp` (Image `docker.io/node:22-alpine`, eigenbau) — ⚠️ **sollte auf DS923 umziehen** (Performance-Restriktion, macmini ist User-Workstation) |
| n8n-mcp | `n8n-mcp.emsenhuber.net` | `10.40.20.167:3001` | `n8n-mcp` (Image `ghcr.io/czlonkowski/n8n-mcp:latest`) — bleibt auf macmini: n8n-Workflows lösen Tool-Calls gegen diesen MCP aus, **lokale Performance-Kopplung gewollt** |
| ha-mcp | `ha-mcp.emsenhuber.net` | `10.40.20.105:9583` | nicht im Bestand (Portainer) — externer Dienst |

**Mac mini ist der n8n-Host, NICHT der zentrale MCP-Host** (User-Direktive 2026-08-28, Performance-Überlegung: User-Workstation soll nicht durch MCP-Clients zusätzlich belastet werden). Der zentrale MCP-Host ist die **DS923** (`nas-bf`, Portainer Endpoint 14). gitea-mcp läuft dort nur historisch; Umzug ist separater Punkt.

**Container-Definitionen leben auf dem macmini** (Docker Desktop), **nicht** im `bf-infra`-Repo. Repo-Quelle ist nur das **FQDN-Mapping im Caddyfile**. Wer den Container umziehen will, ändert das Mapping, nicht die MCP-Config.

## Hosts, die aus dem Repo (IP→Stack) kommen

`docs/nas-vlan20/stacks/*.yml` ist SSoT für Container auf der DS923 (Portainer Endpoint 14) — **dem zentralen MCP-Host**:

| Dienst | Stack-YML | IP | Status |
|---|---|---|---|
| pve-mcp | `pve-mcp.yml` (gitignored) | `10.40.20.173:3000/mcp` | 🟢 deployed |
| shelly-mcp | `mcp/shelly/{Dockerfile,BUILD.md}` im Repo, Stack bewusst nicht im Repo (würde nur User-Direktive "kein MCP-Client" widersprechen). Deploy via Portainer-API direkt. | `10.40.20.180:3030/mcp` (geplant, Container **kein** MCP-Client) | 🟡 staged (Build + Deploy ausstehend) |
| komodo-mcp | — | `10.40.20.176:3000/sse` | 🟡 geplant |
| gitea-mcp | (geplant) | `10.40.20.x:3000/mcp` | 🟡 Umzug macmini → DS923 (separater Punkt, Performance) |
| n8n-mcp | bleibt macmini | `10.40.20.167:3001/mcp` | 🟢 live, **bewusst** nicht umziehen (n8n-Workflow-Kopplung) |

## Hosts, die NICHT als MCP-Client exponiert werden (User-Direktive 2026-08-28)

| Dienst | Warum nicht als MCP-Client | Alternative |
|---|---|---|
| **portainer-mcp** | MCP-Client bietet keinen Mehrwert gegenüber dem Direkt-API-Zugriff (HTTP-Curl / Skript). | Portainer-API direkt: `mcp/portainer/.env` hat `PORTAINER_URL` + `PORTAINER_API_KEY`. Skripte machen die Calls, kein Container-Layer nötig. |
| **shelly-mcp** | Container-Deploy geht via Portainer-API (s.o.). | Genau dasselbe: deployen via Portainer-API, Shelly-Verwaltung via Direkt-Aufrufe gegen die FastMCP-HTTP-Schnittstelle. |

**Entscheid gilt ab sofort.** Wer in `~/.claude.json` oder `~/.config/opencode/opencode.jsonc` einen Block für portainer-mcp oder shelly-mcp anlegt, **macht etwas verkehrt** — `mcp/INVENTORY.md` aktualisieren, kein neuer MCP-Client.

## Drift-Detection

Eine Änderung an einer IP im `caddy/Caddyfile` oder in `docs/nas-vlan20/stacks/*.yml` muss sich in `~/.claude.json` / `~/.config/opencode/opencode.jsonc` widerspiegeln — sonst zeigt der MCP-Client auf eine Adresse, an der der Dienst nicht (mehr) läuft. **Aktuell** ist dieser Sync manuell. Sobald TP34 (Caddyfile via Nautobot/GC) läuft, ist das die Vorlage für eine **MCP-Endpoint-ComplianceRule**: jede MCP-URL in den globalen Configs muss eine IP haben, die im Nautobot-Backend-Set existiert.

## Lehren aus den Backups vom 2026-08-28

Die `.bak-pre-mcp-cleanup-*`-Dateien in `~/.claude.json.*` und `~/.config/opencode/opencode.jsonc.*` zeigen, was **wirklich da war**. Hätte ich sie vor dieser Session gelesen, wäre mir aufgefallen:

1. **`gitea-mcp` + `n8n-mcp` waren in `~/.claude.json` nie eingetragen**, obwohl die Container laufen. Drift seit unknown. (In `opencode.jsonc` waren sie.)
2. **`shelly-mcp` war in beiden Configs nie aktiv** (immer `enabled=false`), und der Portainer-Stand war "kein Container" — der "folgt noch"-Pfad war doppelt blockiert.
3. **Backups lesen ist Pflicht**, nicht Kür. Wer eine Vorgängersession zusammenfasst, schreibt die Backups auf die Liste — nicht nur das, was im Working-Tree des Repos liegt.

## Stand
- 2026-08-28 (zweite Fassung, nach User-Korrektur "pfui, schäm dich"): Symlink `~/.config/opencode/skills/projektstatus` wurde wieder entfernt (opencode-Verzeichnis leer, kommt später neu).
- Mac mini als zentraler MCP-Host bestätigt: gitea-mcp `:3000` + n8n-mcp `:3001` (Portainer Endpoint 20).
- `portainer-mcp` + `shelly-mcp` sind **keine** MCP-Clients (Direkt-API-Wrapper reicht).