Connecter un assistant IA

Cette page connecte un assistant IA compatible avec 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 les clients MCP à se connecter. Tant que cette option est désactivée, chaque appel MCP répond 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> :

Serveur	Adresse
Appareils	`https://<your host>/tenant/<tenantId>/api/mcp/iot_device`
Télémétrie	`https://<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 que vous voyez dans votre navigateur.

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

Pour voir chaque serveur et chaque outil 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.

Ouvrez Clés API > Nouvelle clé API.
Nommez-la d’après l’assistant et la personne, par exemple « Assistant bureau – Alex ».
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.
Définissez une courte expiration et, si l’assistant fonctionne toujours depuis un même réseau, une liste d’autorisation IP.
Créez la clé et copiez-la.
Dans les paramètres MCP de l’assistant, ajoutez un serveur de type HTTP (appelé parfois « Streamable HTTP ») avec l’adresse ci-dessus et l’en-tête :

Authorization: Bearer sk_live_…

Répétez l’opération pour le second serveur, avec la même clé.

Beaucoup d’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 étiquettes. 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 connexion (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.

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.
L’assistant ouvre une page Hermetry. Connectez-vous si on vous le demande.
Hermetry affiche Connecter à cet espace de travail ? avec « Son identité est publiée à . » et « Il agit en votre nom, et jamais avec plus que votre accès dans cet espace de travail. » Pour une connexion en lecture seule, il ajoute « Il peut lire ce que vous pouvez lire via les outils IA de l’espace de travail. Il ne peut rien modifier. »
Vérifiez le nom de l’application et l’hôte, puis sélectionnez Connecter. Annuler renvoie l’assistant sans accès.
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 n’est pas connu d’Hermetry. 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é.

Déroulement de la connexion

Pour les personnes qui gèrent le côté assistant :

Le serveur répond à un appel non authentifié par 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 (aussi 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 correspondant à la base MCP de cet espace de travail ou à un serveur.
Portées : mcp:read ; mcp:write n’est accordée que dans les 15 minutes suivant une connexion 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 durent 10 minutes. Les jetons de rafraîchissement sont remplacés à chaque utilisation ; réutiliser un ancien révoque la connexion. Une connexion dure au maximum 90 jours.
Les jetons peuvent être révoqués à <base>/api/mcp/oauth/revoke.

Vérifier que cela fonctionne

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

Symptôme	Cause
`401`	Clé 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
`404`	Le nom du serveur est erroné, ou son module n’est pas activé pour votre organisation
Aucun outil listé	La clé ou vous n’avez pas les autorisations des outils, ou les outils sont désactivés
`405`	L’assistant a utilisé `GET` ; il doit utiliser `POST` (Streamable HTTP, réponses JSON)
Une session basée sur un cookie est refusée	MCP n’accepte qu’une clé ou un jeton dans l’en-tête `Authorization`
`403` depuis une page web	Les appels portant un `Origin` de navigateur d’un autre site sont refusés
`415`	La requête n’a pas été envoyée en `application/json`

Notes techniques

Transport : Streamable HTTP, POST uniquement, réponses JSON, sans sessions (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 aussi acceptées.
Corps de requête jusqu’à 64 KiB ; Content-Type: application/json.
Chaque serveur publie un nom technique que votre assistant peut afficher. Les noms clairs commençant par hermetry-, que vous pouvez modifier pour votre organisation, sont en cours de développement.