Konfigurationsseite für die KI-Schnittstelle verstehen

Im Register „KI (MCP)“ legen Sie fest, ob eine KI auf Ihre XTENSION Nodes zugreifen darf, wie sie sich ausweisen muss und wie Sie Ihre KI-Anwendung verbinden. Im Folgenden werden alle Bereiche der Seite im Detail erklärt.

Die Seite gliedert sich in folgende Bereiche:

• Register „KI (MCP)“ (1): In der Navigation steht das Register direkt nach „Energiesteuerung“.
• „Was ist die KI-Schnittstelle (MCP)?“ (2): Eine kurze Erklärung der Funktion. Fehlt eine gültige Lizenz, erscheint hier zusätzlich der Hinweis „Die KI-Schnittstelle benötigt eine gültige Lizenz. Ohne Lizenz werden alle Anfragen abgelehnt.“
• „Betriebsart“ (3) und darunter „Authentifizierung“, „Verbindung einrichten“, „Verfügbare Funktionen“ und „Sicherheitshinweise“.
• Werkzeugleiste „Funktionen“ rechts mit „Einstellungen speichern“ (4) und „Schlüssel erzeugen“ bzw. „Neuen Schlüssel erzeugen“ (5). „Einstellungen speichern“ ist nur aktiv, wenn es ungespeicherte Änderungen gibt.

1. Betriebsart

Mit der Betriebsart legen Sie fest, ob und in welchem Umfang eine KI auf den Baustein zugreifen darf:

• „Aus“ (1): Die Schnittstelle ist abgeschaltet und beantwortet keine Anfragen. Das ist der Auslieferungszustand.
• „Nur lesen“ (2): Die KI darf Daten, Wertfolgen, Funktionen und Zustände abfragen, aber nichts verändern. Für die meisten Anwendungsfälle – Auswertungen, Fragen zum Energieverbrauch, Fehlersuche – reicht diese Betriebsart aus.
• „Lesen & schreiben“ (3): Die KI darf zusätzlich Werte am Gira X1 setzen und die Energiesteuerung ein- und ausschalten. Dabei werden echte Geräte geschaltet. Diese Betriebsart erfordert immer einen Schlüssel.

Solange Änderungen noch nicht gespeichert sind, erscheint unter den Optionen der Hinweis „Die Änderungen sind noch nicht gespeichert.“ Die neue Betriebsart gilt erst, wenn Sie auf „Einstellungen speichern“ geklickt haben.

2. Authentifizierung

Hier legen Sie fest, wie sich eine KI-Anwendung gegenüber dem Baustein ausweisen muss:

• „API-Schlüssel (empfohlen)“ (4): Jede Anfrage muss den Schlüssel im Header Authorization: Bearer <Schlüssel> mitsenden. Anfragen ohne oder mit falschem Schlüssel werden abgelehnt.
• „Keine Authentifizierung“ (5): Jedes Gerät im lokalen Netz kann die Schnittstelle nutzen. Diese Option ist nur in der Betriebsart „Nur lesen“ wählbar. Ist sie aktiv, warnt die Seite: „Ohne Authentifizierung kann jedes Gerät im lokalen Netz die Daten des Bausteins abfragen.“

Bei Authentifizierung per API-Schlüssel zeigt die Zeile „Schlüssel“ den Status:

• „Noch kein Schlüssel erzeugt – ohne Schlüssel werden alle Anfragen abgelehnt.“: Erzeugen Sie zuerst einen Schlüssel.
• „Vorhanden (endet auf …Zz9Q, erstellt am …)“: Es gibt einen gültigen Schlüssel. Zur Wiedererkennung werden nur die letzten vier Zeichen und das Erstellungsdatum angezeigt.

3. Schlüssel erzeugen und erneuern

Über „Schlüssel erzeugen“ (6) bzw. die gleichnamige Funktion in der Werkzeugleiste erstellen Sie einen neuen Schlüssel. Existiert bereits einer, fragt die Seite vorher nach, denn der bisherige Schlüssel wird sofort ungültig. Alle KI-Anwendungen, die ihn verwenden, müssen danach mit dem neuen Schlüssel eingerichtet werden.

Nach dem Erzeugen erscheint der Schlüssel (1) mit dem Hinweis „Dieser Schlüssel wird nur jetzt angezeigt. Kopieren Sie ihn und bewahren Sie ihn sicher auf.“ Über „Kopieren“ (2) landet er in der Zwischenablage. Alle Schlüssel beginnen mit xtn_.

Tipp: Ein neuer Schlüssel ist sofort gültig – auch ohne „Einstellungen speichern“. Die Betriebsart und die Art der Authentifizierung müssen Sie dagegen immer speichern.

4. Verbindung einrichten

In diesem Abschnitt finden Sie alles, was Sie in Ihrer KI-Anwendung eintragen müssen:

• „Adresse“ (1): Die Adresse des MCP-Servers, immer in der Form http://<ip-adresse-vom-girax1>:8081/mcp. Mit „Kopieren“ (2) übernehmen Sie sie in die Zwischenablage.
• „Übertragung“: Der Baustein spricht das Übertragungsverfahren Streamable HTTP in der MCP-Version 2025-06-18 (ältere Versionen 2025-03-26 und 2024-11-05 werden ebenfalls verstanden).
• „VS Code / GitHub Copilot (.vscode/mcp.json)“ (3): Fertige Konfiguration für Visual Studio Code.
• „Claude Desktop (claude_desktop_config.json)“ (4): Fertige Konfiguration für Claude Desktop. Claude Desktop verbindet sich über das Hilfsprogramm mcp-remote, das Node.js voraussetzt. Der Parameter --allow-http ist nötig, weil der Gira X1 kein HTTPS anbietet.

In beiden Konfigurationen steht <KEY> als Platzhalter für Ihren Schlüssel. Direkt nach dem Erzeugen eines Schlüssels wird er automatisch eingesetzt, sodass Sie die Konfiguration nur noch kopieren müssen. Die genaue Einrichtung beschreibt das Kapitel KI-Anwendungen einrichten.

5. Verfügbare Funktionen

Die Tabelle zeigt alle Funktionen, die der Baustein einer KI anbietet:

• „Funktion“ (1) und „Beschreibung“: Technischer Name und Zweck der Funktion.
• „Zugriff“ (2): „Lesen“ oder „Schreiben“. Schreibende Funktionen können Geräte schalten.
• „Verfügbar“ (3): Ob die KI die Funktion mit der gespeicherten Betriebsart nutzen kann. In der Betriebsart „Nur lesen“ stehen schreibende Funktionen auf „Nein“.

Über der Tabelle können zwei Hinweise erscheinen:

• „Der Zugriff auf die Funktionen des Gira X1 ist am Baustein abgeschaltet …“: Der Parameter „Listenfunktion aktiviert“ am Grundbaustein ist aus. Die Funktionen mit x1_ im Namen sind dann nicht nutzbar.
• „Der Baustein ist nicht am Gira X1 angemeldet …“: Melden Sie sich in der Benutzeroberfläche mit einem Benutzer des Gira X1 an, damit die KI Funktionen und Werte des Gira X1 nutzen kann.

Was jede Funktion im Einzelnen liefert, erklärt das Kapitel Funktionen der KI-Schnittstelle.

6. Sicherheitshinweise

Am Ende der Seite fasst der Abschnitt „Sicherheitshinweise“ die wichtigsten Regeln zusammen. Lesen Sie diese vor dem Einschalten der Betriebsart „Lesen & schreiben“ unbedingt durch. Ausführliche Erläuterungen finden Sie im Kapitel Sicherheit und Datenschutz.