byteforge-aegis-mcp

Ein schreibgeschützter MCP-Server über die ByteForge Aegis Admin-API, bereitgestellt als Container hinter nginx mit Gatekeeper-Authentifizierung.

Warum

Agenten, die an Aegis und an Tenant-Integrationen arbeiten, müssen immer wieder die Frage beantworten: „Was ist tatsächlich in der Produktion konfiguriert?“ – Ist die Webhook-URL gesetzt, ist allow_self_registration aktiv, welche Sites existieren, existiert dieser Benutzer. Vor diesem Server wurde diese Frage mit handgestrickten Curls beantwortet, die den Master-API-Key trugen, oder gar nicht – eine Tenant-Provisioning-Anfrage wurde einst teilweise aufgrund einer Behauptung abgezeichnet, weil die Site-Konfiguration nicht ausgelesen werden konnte.

Related MCP server: readonly-mcp-akamai

Schreibgeschützt durch Konstruktion

Jedes Tool wird auf einen GET-Request abgebildet. Der Aegis-Client, den dieser Server umschließt, stellt auch create_site, update_site, delete_site, delete_user und ähnliche bereit – keines davon ist hier erreichbar, und keines sollte hinzugefügt werden. Der Wert dieses Servers liegt darin, dass er einem Agenten übergeben werden kann, ohne dass die Möglichkeit besteht, den Produktionszustand zu ändern. Ein mutierender Server gehört, falls jemals gewünscht, in eine separate und separat autorisierte Bereitstellung.

Werkzeuge

aegis_get_site und aegis_list_users akzeptieren sowohl eine Domain als auch eine UUID. Die Admin-API adressiert Sites nur per UUID (utils/identifiers.py resolve_site lehnt Nicht-UUIDs ab), daher wird eine Domain zuerst über den öffentlichen by-domain-Lookup aufgelöst – Aufrufer kennen fast immer die Domain, nicht die UUID.

Secrets in Antworten

Site-Reads enthalten tenant_api_key, webhook_secret und mailgun_api_key in voller Länge. Dies war eine bewusste Entscheidung von @jmazzahacks anstelle der Rückgabe von Präsenz-Booleans. Die Konsequenz: Alles, was hier gelesen wird, landet im Transkript des aufrufenden Agenten, daher sollten Antworten nicht in Tickets oder andere geteilte Oberflächen eingefügt werden. AEGIS_MASTER_API_KEY erstreckt sich über jede Site auf der Instanz.

Konfiguration

Siehe example.env.

Lokale Entwicklung

uv venv --python 3.13 .venv
source .venv/bin/activate
uv pip install -r requirements.txt

AEGIS_API_URL=https://aegis.example.com \
AEGIS_MASTER_API_KEY=... \
MCP_TRANSPORT=stdio \
python aegis_mcp_server.py

Die venv befindet sich in .venv/ und nicht im Repository-Stammverzeichnis, wie es die benachbarten Aegis-Repos tun – uv venv weigert sich, eine in einem nicht leeren Verzeichnis zu erstellen.

Um es über das Netzwerk so zu testen, wie es bereitgestellt wird:

MCP_TRANSPORT=streamable-http FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=8931 \
AEGIS_API_URL=... AEGIS_MASTER_API_KEY=... python aegis_mcp_server.py &

curl -s -X POST http://127.0.0.1:8931/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Ein tools/list, das ohne vorheriges initialize erfolgreich ist, ist das Signal, dass der zustandslose Modus aktiv ist.

Build und Veröffentlichung

./build-publish.sh            # or --no-cache

Veröffentlicht ghcr.io/jmazzahacks/byteforge-aegis-mcp:<n> und :latest, und erhöht dann VERSION. VERSION ist in .gitignore und wird vollständig vom Skript verwaltet – niemals manuell bearbeiten.

Im Gegensatz zu byteforge-aegis baut dieses Image VERSION nicht in sich selbst ein, daher ist die Reihenfolge „Schreiben nach Build“ des Skripts hier korrekt. Falls jemals ein Version-Endpunkt hinzugefügt wird, muss das Schreiben vor docker build verschoben werden, sonst meldet jedes Image eine Version zurück.

Bereitstellung

Läuft hinter einem mcp.<domain>-Dach-Vhost mit Gatekeeper auth_request-Authentifizierung. Siehe nginx-mcp-aegis.conf für den Location-Block. Der Container gibt keinen Host-Port frei – nginx erreicht ihn über den Containernamen im gemeinsamen Docker-Netzwerk, was wichtig ist, da der Master-Key eine direkte Exposition inakzeptabel macht.

Transport

streamable-http mit stateless_http=True. Nicht SSE: Wenn der langlebige SSE-GET von Claude Code stirbt, stellt er die Verbindung ohne erneutes Ausführen von initialize wieder her, der Server sieht zuerst tools/call, und der resultierende -32602 blockiert den Client, bis ein manuelles /mcp-Reload erfolgt. Zustandsloses streamable-http hat keinen Sitzungszustand zu verlieren, daher ist dieser Fehler strukturell unmöglich.