KI-Assistenten verbinden

Diese Seite verbindet einen KI-Assistenten, der MCP unterstützt, mit Ihrer Hermetry-Organisation. Was der Assistent danach tun kann, wird unter KI-Assistenten (MCP) erklärt.

Bevor Sie beginnen

Ein Administrator hat Einstellungen > MCP > MCP-Clients die Verbindung erlauben aktiviert. Solange diese Option aus ist, antwortet jeder MCP-Aufruf mit 403 „MCP is switched off for this workspace (Settings → MCP)“.
Sie besitzen MCP-Clients verbinden (mcp_server.connect). Jede integrierte Rolle hat sie.
Sie besitzen die Berechtigungen der Werkzeuge, die Sie nutzen möchten: Geräte anzeigen für die Gerätewerkzeuge und die Leseberechtigung für Telemetrie für die Telemetriewerkzeuge.

Ihre Server-Adressen

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

Server	Adresse
Geräte	`https://<your host>/tenant/<tenantId>/api/mcp/iot_device`
Telemetrie	`https://<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 zur 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 MCP-Clients verbinden 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 bei denen Sie einen HTTP-Header setzen können.

Öffnen Sie API-Schlüssel > Neuer API-Schlüssel.
Benennen Sie ihn nach dem Assistenten und der Person, zum Beispiel „Desktop-Assistent – Alex“.
Setzen Sie unter Modulberechtigungen ein Häkchen bei MCP-Clients verbinden (Gruppe MCP) und bei der Voreinstellung Nur lesen des Geräte-Moduls und der Telemetrie.
Legen Sie eine kurze Gültigkeitsdauer fest und, falls der Assistent immer aus einem Netzwerk heraus läuft, eine IP-Allowlist.
Erstellen Sie den Schlüssel und kopieren Sie ihn.
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_…

Wiederholen Sie dies für den zweiten Server mit demselben Schlüssel.

Viele Assistenten nehmen eine JSON-Konfiguration wie diese an (die genauen Datei- und Feldnamen hängen 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 links sind Ihre eigenen Bezeichnungen. Der Schlüssel handelt in Ihrem Namen und ist auf das beschränkt, 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, bei denen Sie einen „benutzerdefinierten Connector“ oder einen „Remote-MCP-Server“ über eine Adresse hinzufügen können.

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 etwaige Felder für Client-ID und Secret leer.
Der Assistent öffnet eine Hermetry-Seite. Melden Sie sich an, falls Sie dazu aufgefordert werden.
Hermetry zeigt Verbindung mit diesem Arbeitsbereich herstellen? mit „Its identity is published at .“ und „It acts as you, and never with more than your access in this workspace.“ Bei einer schreibgeschützten Verbindung kommt „It can read what you can read through the workspace’s AI tools. It cannot change anything.“ hinzu.
Prüfen Sie den App-Namen und den Host und wählen Sie dann Verbinden. Abbrechen schickt den Assistenten ohne Zugriff zurück.
Wiederholen Sie dies für den Telemetrie-Server. Jeder Server wird einzeln mit seiner eigenen Adresse hinzugefügt.

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

Wenn Hermetry Diese App kann keine Verbindung herstellen anzeigt, ist der Host der App nicht bekannt. Hermetry akzeptiert eine integrierte Liste bekannter KI-Apps; ein Administrator kann unter Einstellungen > MCP > Weitere KI-Apps weitere Hosts hinzufügen. Siehe MCP-Einstellungen und Sicherheit.

Was während der Anmeldung geschieht

Für die Personen, die die Assistentenseite betreiben:

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 Sie 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 genau einen Server angibt.
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.

Symptom	Ursache
`401`	Falscher 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
`404`	Der Servername ist falsch, oder dessen Modul ist für Ihre Organisation nicht aktiviert
Keine Werkzeuge aufgelistet	Dem Schlüssel oder Ihnen fehlen die Berechtigungen der Werkzeuge, oder die Werkzeuge sind ausgeschaltet
`405`	Der Assistent verwendete `GET`; er muss `POST` verwenden (Streamable HTTP, JSON-Antworten)
Eine cookie-basierte Sitzung wird abgelehnt	MCP akzeptiert nur einen Schlüssel oder ein Token im `Authorization`-Header
`403` von einer Webseite	Aufrufe mit einem browserseitigen `Origin` einer anderen Website werden abgelehnt
`415`	Die 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.
Protokollrevision 2025-11-25; neuere Revisionen werden ebenfalls beantwortet.
Anfragekörper bis zu 64 KiB; Content-Type: application/json.
Jeder Server meldet einen technischen Namen, den Ihr Assistent anzeigen darf. Klare Namen, die mit hermetry- beginnen und die Sie für Ihre Organisation ändern können, sind in Entwicklung.