Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

Connecter un assistant IA

Trouvez les adresses de vos serveurs MCP, connectez un assistant IA avec une clé API ou avec une ouverture de session, et vérifiez que cela fonctionne.

Cette page connecte un assistant IA compatible MCP à votre organisation Hermetry. Ce que l’assistant peut ensuite faire est expliqué dans Assistants IA (MCP).

Avant de commencer

  • Un administrateur a activé Paramètres > MCP > Autoriser la connexion des clients MCP. Tant que cette option est désactivée, chaque appel MCP renvoie 403 « MCP is switched off for this workspace (Settings → MCP) ».
  • Vous disposez de Connecter les clients MCP (mcp_server.connect). Tous les rôles intégrés l’ont.
  • Vous disposez des autorisations des outils que vous voulez utiliser : Voir les appareils pour les outils d’appareils, et l’autorisation de lecture de la télémétrie pour les outils de télémétrie.

Vos adresses de serveurs

Chaque module dispose de son propre serveur MCP. Son adresse est l’adresse de votre espace de travail suivie de /api/mcp/<server> :

ServeurAdresse
Appareilshttps://<your host>/tenant/<tenantId>/api/mcp/iot_device
Télémétriehttps://<your host>/tenant/<tenantId>/api/mcp/telemetry

Si votre organisation dispose de sa propre adresse web (par exemple https://acme.<your host>), l’adresse est https://acme.<your host>/api/mcp/iot_device. Utilisez la forme qui correspond à l’adresse affichée dans votre navigateur.

Ajoutez les deux serveurs à votre assistant : les outils de télémétrie ont besoin des identifiants d’appareils renvoyés par list_devices.

Pour voir tous les serveurs et outils que vous pouvez utiliser, appelez l’index avec une clé API qui dispose de Connecter les clients MCP :

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 : se connecter avec une clé API

Utilisez cette option pour les assistants qui fonctionnent sur votre ordinateur ou sur votre propre serveur et qui vous permettent de définir un en-tête HTTP.

  1. Ouvrez Clés API > Nouvelle clé API.
  2. Nommez-la d’après l’assistant et la personne, par exemple « Assistant bureau – Alex ».
  3. Sous Autorisations du module, cochez Connecter les clients MCP (groupe MCP), ainsi que le préréglage Lecture seule du module appareils et de la télémétrie.
  4. Définissez une courte durée de validité et, si l’assistant fonctionne toujours depuis un même réseau, une liste d’autorisation IP.
  5. Créez la clé et copiez-la.
  6. Dans les paramètres MCP de l’assistant, ajoutez un serveur de type HTTP (parfois appelé « Streamable HTTP ») avec l’adresse ci-dessus et l’en-tête :
Authorization: Bearer sk_live_…
  1. Répétez l’opération pour le second serveur, avec la même clé.

De nombreux assistants acceptent une configuration JSON de ce type (le nom exact du fichier et des champs dépend de l’assistant) :

{
  "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_…" }
    }
  }
}

Les noms à gauche sont vos propres libellés. La clé agit en votre nom, limitée à ce que vous avez coché. Voir Clés MCP et applications connectées.

Option 2 : se connecter avec une ouverture de session (OAuth)

Utilisez cette option pour les assistants hébergés sur le web qui vous permettent d’ajouter un « connecteur personnalisé » ou un « serveur MCP distant » par adresse.

  1. Dans l’assistant, ajoutez un connecteur avec l’adresse du serveur, par exemple https://<your host>/tenant/<tenantId>/api/mcp/iot_device. Laissez vides les champs d’identifiant et de secret client éventuels.
  2. L’assistant ouvre une page Hermetry. Ouvrez une session si vous y êtes invité.
  3. Hermetry affiche Connecter nom de l’application à cet espace de travail ? avec « Son identité est publiée à hôte de l’application. » et « Elle agit en votre nom, et jamais avec plus d’accès que le vôtre dans cet espace de travail. » Pour une connexion en lecture seule, il ajoute « Elle peut lire ce que vous pouvez lire via les outils IA de l’espace de travail. Elle ne peut rien modifier. »
  4. Vérifiez le nom et l’hôte de l’application, puis sélectionnez Connecter. Annuler renvoie l’assistant sans accès.
  5. Répétez l’opération pour le serveur de télémétrie. Chaque serveur est ajouté séparément, avec sa propre adresse.

L’application apparaît dans Applications connectées. « Vous pouvez la déconnecter à tout moment dans Applications connectées. »

Si Hermetry affiche Cette application ne peut pas se connecter, l’hôte de l’application ne fait pas partie de ceux que Hermetry connaît. Hermetry accepte une liste intégrée d’applications IA connues ; un administrateur peut ajouter d’autres hôtes sous Paramètres > MCP > Autres applications IA. Voir Paramètres MCP et sécurité.

Ce qui se passe pendant l’ouverture de session

Pour les personnes qui gèrent la partie assistant :

  • Le serveur répond à un appel non authentifié avec 401 et WWW-Authenticate: Bearer resource_metadata="<base>/api/mcp/oauth/protected-resource/<server>".
  • Les métadonnées du serveur d’autorisation se trouvent à <base>/api/mcp/oauth/.well-known/oauth-authorization-server (également openid-configuration).
  • Les clients s’identifient avec un identifiant client qui est l’adresse https d’un document de métadonnées client ; il n’y a pas d’enregistrement dynamique de client.
  • Seul le flux à code d’autorisation avec PKCE (S256) est accepté, avec une adresse de redirection exacte (https, ou http sur la machine locale pour les applications de bureau) et une resource qui correspond à la base MCP de cet espace de travail ou à un serveur.
  • Portées : mcp:read ; mcp:write n’est accordé que dans les 15 minutes suivant une ouverture de session récente (« Sign out and sign in again, then connect the app: letting it change records needs a fresh sign-in. »). Les outils IoT n’ont besoin que de mcp:read.
  • Les jetons d’accès sont valides 10 minutes. Les jetons d’actualisation sont remplacés à chaque utilisation ; réutiliser un ancien jeton révoque la connexion. Une connexion dure 90 jours au maximum.
  • Les jetons peuvent être révoqués à <base>/api/mcp/oauth/revoke.

Vérifier que cela fonctionne

Demandez à l’assistant « List my devices ». Il doit appeler list_devices et répondre avec des noms de votre organisation.

SymptômeCause
401Clé erronée ou expirée, ou clé d’une autre organisation ; ou l’application a été déconnectée
403 « MCP is switched off for this workspace »Un administrateur doit activer MCP
404Le nom du serveur est erroné, ou son module n’est pas activé pour votre organisation
Aucun outil listéLa clé ou vous-même n’avez pas les autorisations des outils, ou les outils sont désactivés
405L’assistant a utilisé GET ; il doit utiliser POST (Streamable HTTP, réponses JSON)
Une session basée sur les cookies est refuséeMCP accepte uniquement une clé ou un jeton dans l’en-tête Authorization
403 depuis une page webLes appels portant un Origin de navigateur d’un autre site sont refusés
415La requête n’a pas été envoyée en application/json

Notes techniques

  • Transport : Streamable HTTP, POST uniquement, réponses JSON, sans session (pas de Mcp-Session-Id). GET et DELETE répondent 405.
  • Révision du protocole 2025-11-25 ; les révisions plus récentes sont également acceptées.
  • Corps de requête jusqu’à 64 KiB ; Content-Type: application/json.
  • Chaque serveur indique un nom technique que votre assistant peut afficher.