Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

KI-Assistent verbinden

Finden Sie Ihre MCP-Server-Adressen, verbinden Sie einen KI-Assistenten mit einem API-Schlüssel oder mit einer Anmeldung und prüfen Sie, ob er funktioniert.

Diese Seite verbindet einen KI-Assistenten, der MCP unterstützt, mit Ihrer Hermetry-Organisation. Was der Assistent anschließend tun kann, wird unter KI-Assistenten (MCP) erläutert.

Bevor Sie beginnen

  • Ein Administrator hat Einstellungen > MCP > Let MCP clients connect eingeschaltet. Solange diese Option aus ist, antwortet jeder MCP-Aufruf mit 403 „MCP is switched off for this workspace (Settings → MCP)“.
  • Sie besitzen Connect MCP clients (mcp_server.connect). Jede eingebaute Rolle hat sie.
  • Sie besitzen die Berechtigungen der Werkzeuge, die Sie nutzen möchten: View devices für die Gerätewerkzeuge und die Leseberechtigung für Telemetrie für die Telemetriewerkzeuge.

Ihre Server-Adressen

Jedes Modul hat seinen eigenen MCP-Server. Seine Adresse besteht aus der Adresse Ihres Arbeitsbereichs, gefolgt von /api/mcp/<server>:

ServerAdresse
Gerätehttps://<your host>/tenant/<tenantId>/api/mcp/iot_device
Telemetriehttps://<your host>/tenant/<tenantId>/api/mcp/telemetry

Wenn Ihre Organisation eine eigene Webadresse hat (zum Beispiel https://acme.<your host>), lautet die Adresse https://acme.<your host>/api/mcp/iot_device. Verwenden Sie die Form, die zu der Adresse passt, die Sie in Ihrem Browser sehen.

Fügen Sie beide Server zu Ihrem Assistenten hinzu: Die Telemetriewerkzeuge benötigen die Geräte-IDs, die list_devices zurückgibt.

Um alle Server und Werkzeuge zu sehen, die Sie nutzen können, rufen Sie den Index mit einem API-Schlüssel auf, der Connect MCP clients besitzt:

curl -s "https://<your host>/tenant/<tenantId>/api/mcp" -H "Authorization: Bearer sk_live_…"
{
  "enabled": true,
  "servers": [
    { "server": "iot_device", "path": "/api/mcp/iot_device", "tools": [
      { "name": "get_device", "title": "Get a device", "kind": "read" },
      { "name": "list_devices", "title": "List devices", "kind": "read" } ] },
    { "server": "telemetry", "path": "/api/mcp/telemetry", "tools": [
      { "name": "get_latest_readings", "title": "Get latest readings", "kind": "read" },
      { "name": "get_reading_series", "title": "Get a reading series", "kind": "read" } ] }
  ]
}

Option 1: Verbindung mit einem API-Schlüssel

Verwenden Sie dies für Assistenten, die auf Ihrem Computer oder Ihrem eigenen Server laufen und das Setzen eines HTTP-Headers erlauben.

  1. Öffnen Sie API Keys > New API Key.
  2. Benennen Sie ihn nach dem Assistenten und der Person, zum Beispiel „Desktop assistant – Alex“.
  3. Setzen Sie unter Module permissions den Haken bei Connect MCP clients (Gruppe MCP) sowie die Voreinstellung Read only des Geräte-Moduls und der Telemetrie.
  4. Legen Sie eine kurze Gültigkeitsdauer fest und, falls der Assistent immer aus demselben Netzwerk läuft, eine IP allowlist.
  5. Erstellen Sie den Schlüssel und kopieren Sie ihn.
  6. Fügen Sie in den MCP-Einstellungen des Assistenten einen Server vom Typ HTTP (manchmal „Streamable HTTP“ genannt) mit der oben genannten Adresse und dem Header hinzu:
Authorization: Bearer sk_live_…
  1. Wiederholen Sie dies für den zweiten Server mit demselben Schlüssel.

Viele Assistenten nehmen eine JSON-Konfiguration wie diese entgegen (der genaue Datei- und Feldname hängt vom Assistenten ab):

{
  "mcpServers": {
    "hermetry-devices": {
      "type": "http",
      "url": "https://<your host>/tenant/<tenantId>/api/mcp/iot_device",
      "headers": { "Authorization": "Bearer sk_live_…" }
    },
    "hermetry-telemetry": {
      "type": "http",
      "url": "https://<your host>/tenant/<tenantId>/api/mcp/telemetry",
      "headers": { "Authorization": "Bearer sk_live_…" }
    }
  }
}

Die Namen auf der linken Seite sind Ihre eigenen Bezeichnungen. Der Schlüssel handelt als Sie selbst, beschränkt auf das, was Sie angekreuzt haben. Siehe MCP-Schlüssel und verbundene Apps.

Option 2: Verbindung mit einer Anmeldung (OAuth)

Verwenden Sie dies für webbasierte Assistenten, die es erlauben, einen „benutzerdefinierten Connector“ oder „Remote-MCP-Server“ über eine Adresse hinzuzufügen.

  1. Fügen Sie im Assistenten einen Connector mit der Server-Adresse hinzu, zum Beispiel https://<your host>/tenant/<tenantId>/api/mcp/iot_device. Lassen Sie die Felder für Client-ID und Secret leer.
  2. Der Assistent öffnet eine Hermetry-Seite. Melden Sie sich an, falls Sie dazu aufgefordert werden.
  3. Hermetry zeigt Connect app name to this workspace? mit „Its identity is published at app host.“ und „It acts as you, and never with more than your access in this workspace.“ Bei einer Verbindung nur zum Lesen ergänzt es „It can read what you can read through the workspace’s AI tools. It cannot change anything.“
  4. Prüfen Sie Name und Host der App und wählen Sie dann Connect. Cancel schickt den Assistenten ohne Zugriff zurück.
  5. Wiederholen Sie dies für den Telemetrie-Server. Jeder Server wird einzeln mit seiner eigenen Adresse hinzugefügt.

Die App erscheint unter Connected apps. „You can disconnect it at any time in Connected apps.“

Wenn Hermetry This app cannot connect anzeigt, ist der Host der App einer, den Hermetry nicht kennt. Hermetry akzeptiert eine eingebaute Liste bekannter KI-Apps; ein Administrator kann unter Einstellungen > MCP > More AI apps weitere Hosts hinzufügen. Siehe MCP-Einstellungen und Sicherheit.

Was während der Anmeldung geschieht

Für die Personen, die auf Assistentenseite arbeiten:

  • Der Server antwortet auf einen nicht authentifizierten Aufruf mit 401 und WWW-Authenticate: Bearer resource_metadata="<base>/api/mcp/oauth/protected-resource/<server>".
  • Die Metadaten des Autorisierungsservers finden sich unter <base>/api/mcp/oauth/.well-known/oauth-authorization-server (außerdem openid-configuration).
  • Clients identifizieren sich mit einer Client-ID, die die https-Adresse eines Client-Metadatendokuments ist; eine dynamische Client-Registrierung gibt es nicht.
  • Akzeptiert wird nur der Autorisierungscode-Ablauf mit PKCE (S256), mit einer exakten Weiterleitungsadresse (https oder http auf dem lokalen Rechner für Desktop-Apps) und einer resource, die die MCP-Basis dieses Arbeitsbereichs oder einen Server darstellt.
  • Scopes: mcp:read; mcp:write wird nur innerhalb von 15 Minuten nach einer frischen Anmeldung gewährt („Sign out and sign in again, then connect the app: letting it change records needs a fresh sign-in.“). Die IoT-Werkzeuge benötigen nur mcp:read.
  • Zugriffstoken gelten 10 Minuten. Refresh-Token werden bei jeder Verwendung ersetzt; die Wiederverwendung eines alten Tokens widerruft die Verbindung. Eine Verbindung besteht höchstens 90 Tage.
  • Token können unter <base>/api/mcp/oauth/revoke widerrufen werden.

Funktion prüfen

Fragen Sie den Assistenten „List my devices“. Er sollte list_devices aufrufen und mit Namen aus Ihrer Organisation antworten.

SymptomUrsache
401Falscher oder abgelaufener Schlüssel, oder ein Schlüssel einer anderen Organisation; oder die App wurde getrennt
403 „MCP is switched off for this workspace“Ein Administrator muss MCP einschalten
404Der Servername ist falsch oder sein Modul ist für Ihre Organisation nicht aktiviert
Keine Werkzeuge aufgelistetDem Schlüssel oder Ihnen fehlen die Berechtigungen der Werkzeuge, oder die Werkzeuge sind ausgeschaltet
405Der Assistent verwendete GET; er muss POST verwenden (Streamable HTTP, JSON-Antworten)
Eine sitzungsbasierte Cookie-Anmeldung wird abgelehntMCP akzeptiert nur einen Schlüssel oder ein Token im Header Authorization
403 von einer WebseiteAufrufe mit einem browserseitigen Origin einer anderen Website werden abgelehnt
415Die Anfrage wurde nicht als application/json gesendet

Technische Hinweise

  • Transport: Streamable HTTP, nur POST, JSON-Antworten, keine Sitzungen (kein Mcp-Session-Id). GET und DELETE antworten mit 405.
  • Protokollversion 2025-11-25; neuere Versionen werden ebenfalls beantwortet.
  • Anfragekörper bis 64 KiB; Content-Type: application/json.
  • Jeder Server meldet einen technischen Namen, den Ihr Assistent anzeigen darf.