MCP-Setup ist für Erstintegrierende deutlich schwerer als nötig

**Gemeldet von:** Claude (Anthropic), nach praktischem Testlauf des MCP-Servers und
OAuth-Flows gegen eine lokale ai_platform-1.0.0-beta3-Instanz (Verbindung über
`mcp-remote`, Aufruf des `redaxo_status`-Tools, End-to-End verifiziert).

## Zusammenfassung

Der MCP-Server funktioniert korrekt, sobald man versteht, wie seine Teile
zusammenspielen — aber der Weg dahin ist nicht selbsterklärend. Drei
Design-/Doku-Probleme plus konkrete Verbesserungsvorschläge.

## 1. `mcp_require_auth` ist alles-oder-nichts

Bei `mcp_require_auth=1` bekommt **jede** anonyme Anfrage 401 — auch
`initialize` und `tools/list` für ein Tool, das explizit `public: true` trägt.
Das entwertet das `public`-Flag: sobald irgendein geschütztes Tool im Spiel
ist, ist auch das öffentliche für anonyme Clients unerreichbar.

Der Grund ist nachvollziehbar (viele MCP-Clients starten OAuth nur nach einem
401 — Henne-Ei-Problem), aber die Lösung ist zu grob. Vorschlag:
`initialize`/`tools/list` liefern für anonyme Caller immer 200 (gefiltert auf
public Tools), und nur `tools/call` auf ein geschütztes Tool bzw. ein
expliziter Discovery-Hinweis („N weitere Tools verfügbar, Login nötig")
löst die 401-Challenge aus.

## 2. Fehlermeldung ohne Handlungsanweisung

```json
{"jsonrpc":"2.0","id":1,"error":{"code":-32001,"message":"Authentication required"}}
```

sagt nichts darüber, dass die Ursache `mcp_require_auth` ist, nicht ein
kaputter Client. Der `WWW-Authenticate`-Header trägt die Discovery-URL
korrekt — aber nur wer weiß, danach zu suchen, findet sie. Ein Hinweis auch
im JSON-Body würde helfen.

## 3. Kein Verbindungstest für den MCP-Server

Für LLM-Profile gibt es „API-Verbindung testen". Für den MCP-Server — mit
deutlich mehr beweglichen Teilen (Auth-Modus, Scopes, Discovery-URLs) — nicht.
Ein Button, der einen echten anonymen `initialize`-Call absetzt und bei
Fehlkonfiguration warnt („`mcp_require_auth` ist an, aber keine Scopes sind
gemappt — anonyme Clients werden komplett ausgesperrt"), wäre naheliegend.

## 4. Keine Doku für den schnellen lokalen Testweg

README und Skill dokumentieren ausführlich den Produktionsweg (ngrok, mkcert,
YCom-Gruppen, Scope-Mapping). Für „ich will nur schnell ein public Tool lokal
testen, ohne TLS/OAuth-Aufwand" gibt es nichts. Ergänzungsvorschlag, als
eigener Kurzabschnitt vor dem Produktions-Setup:

**Lokal ohne OAuth testen — Tipps:**

- Natives HTTP-Transport (Claude Code, Claude Desktop, jeder Node-basierte
Client) verlangt ein **von Node als vertrauenswürdig erkanntes**
Zertifikat. Ein selbstsigniertes Zertifikat scheitert mit
`DEPTH_ZERO_SELF_SIGNED_CERT` — es gibt keinen Pro-Server-Schalter, das zu
umgehen. Zwei Auswege: ein per `mkcert` erzeugtes, lokal vertrautes
Zertifikat verwenden (README beschreibt das für den Produktions-Fall
bereits), oder auf die `mcp-remote`-stdio-Bridge ausweichen.
- **`mcp-remote` versucht beim Verbinden immer zuerst den vollen
OAuth-Discovery-Flow zu starten** — auch wenn `mcp_require_auth=0` gesetzt
ist und der Server gar keine Auth verlangt. In einer nicht-interaktiven
Umgebung ohne Browser hängt das dann unbegrenzt, ununterscheidbar von einem
toten Server. Das sollte explizit dokumentiert werden, inklusive des
Workarounds, `NODE_TLS_REJECT_UNAUTHORIZED=0` gezielt nur für den
`mcp-remote`-Kindprozess zu setzen (`-e` bei `claude mcp add`), statt
global.
- **Falls die lokale Domain auf `.local` endet und auf macOS getestet wird:**
macOS löst `*.local`-Hostnamen immer zuerst über mDNS/Bonjour auf, noch vor
`/etc/hosts` — auch wenn dort ein passender Eintrag existiert. Das kostet
reproduzierbar mehrere Sekunden pro Anfrage, bei jedem CLI-Tool (curl,
Node, MCP-Client) neu, und sieht aus wie ein hängender Server. Betrifft
nicht den MCP-Server selbst, aber es lohnt sich, das als Diagnose-Hinweis
in die lokale Testanleitung aufzunehmen — Empfehlung: direkt gegen die IP
testen, oder für lokale Dev-Domains eine nicht-mDNS-TLD wie `.test`
verwenden.
- Minimaler Testpfad, der ganz ohne OAuth auskommt: `mcp_enabled=1`,
`mcp_require_auth=0`, dann `tools/list` und `tools/call` mit `curl` gegen
`/mcp` — verifiziert Server und Tool-Handler, bevor überhaupt OAuth ins
Spiel kommt.

## 5. Keine „Anleitung"-Tab-Parität mit ai_changes

Für Änderungswünsche rendert das Addon `.claude/skills/ai-platform-changes/SKILL.md`
direkt im Backend als Doku-Tab für Redakteure. Für MCP gibt es dieses
Pendant nicht, obwohl `.claude/skills/ai-platform-mcp/SKILL.md` inhaltlich
schon fast das nötige Material enthält — nur eben nur für Claude sichtbar,
nicht für den Admin im Backend. Ein „Anleitung"-Tab unter *MCP Server*
nach demselben Muster würde die Lücke schließen, ohne neuen Inhalt zu
erfordern.

## 6. Änderungswünsche-Abgrenzung erst zu spät im Text

Dass Änderungswünsche bewusst *nicht* über MCP laufen, ist eine gute
Design-Entscheidung — aber der naheliegendste Reflex eines
Erstintegrierenden ist genau die falsche Annahme, dass ein
Content-Change-Tool dort zu finden sein müsste. Ein Satz dazu direkt am
Anfang des MCP-Abschnitts (statt erst nach mehreren hundert Zeilen) würde
diese Verwirrung früh abfangen.

Start with the MCP server implementation and the documented entry points in README, .claude/skills/ai-platform-mcp/SKILL.md, and .claude/skills/ai-platform-changes/SKILL.md. Review the existing MCP setup, authentication flow, and ai_changes Anleitung tab before separating behavior, connection-test, and documentation work. Done means the agreed MCP behavior is covered, the local test path is documented, and MCP has equivalent backend guidance.

Written by the indexing model from the issue text.