MCP Server

Le plugin McpServer exécute un serveur Model Context Protocol (MCP) directement sur le Miniserver. Il permet aux assistants et agents IA d'interroger l'état de votre installation et d'envoyer des commandes aux contrôles, en utilisant vos pièces, catégories et noms de contrôles existants — sans service cloud propre.

L'accès est protégé par la connexion Loxone. Un assistant qui se connecte doit s'authentifier avec un compte utilisateur Loxone et ne peut voir et commander que ce que cet utilisateur est autorisé à utiliser. Créez un utilisateur dédié avec les droits minimaux dont l'assistant a besoin.

Table des matières

• Vue d'ensemble
• Configuration
• Prérequis
• Accès et autorisations
• Ce qu'un assistant peut faire
• Trouver votre URL MCP
• Connecter votre assistant
• Proxy inverse ou domaine personnalisé
• Entrées, sorties, propriétés

Vue d'ensemble↑

Model Context Protocol (MCP) est une norme ouverte qui permet aux assistants IA de se connecter à des systèmes externes au moyen d'un ensemble d'outils bien défini. Ce plugin implémente un serveur MCP pour le Miniserver, afin qu'un assistant connecté puisse trouver des contrôles, lire leur état actuel et déclencher des commandes sans aucun service cloud.

Le serveur lit la structure de l'installation depuis le Miniserver (pièces, catégories, contrôles) et la présente à l'assistant. Les requêtes de l'assistant sont traduites en commandes de contrôle identiques à celles utilisées par les applications Loxone, aucune configuration supplémentaire des contrôles individuels n'est donc nécessaire.

Configuration↑

Ajoutez le plugin McpServer à l'installation et laissez-le démarrer. Votre assistant se connecte à l'URL MCP du plugin — il existe une adresse pour l'accès via Internet et une autre pour le réseau local. Consultez "Trouver votre URL MCP" ci-dessous pour savoir comment les obtenir, ainsi que "Connecter votre assistant" pour les étapes concernant les assistants courants. Collez l'adresse adaptée à votre assistant, lors de sa première connexion, vous vous authentifiez avec un compte utilisateur Loxone pour accorder l'accès.

Aucun compte tiers ni service externe n'est requis. L'assistant s'authentifie directement auprès du Miniserver, et chaque requête s'exécute avec les autorisations de l'utilisateur Loxone connecté.

Prérequis↑

Un Miniserver prenant en charge les plugins (.LxAddOn) est requis, ainsi qu'un assistant ou agent compatible MCP capable d'atteindre le point de terminaison publié, et un compte utilisateur Loxone avec lequel l'assistant pourra s'authentifier.

Un assistant ne peut voir et commander que ce que son utilisateur Loxone est autorisé à utiliser. Accordez à l'utilisateur dédié les droits minimaux requis, et révoquez l'accès à tout moment en désactivant cet utilisateur ou en supprimant la connexion.

Accès et autorisations↑

Lorsqu'un assistant se connecte, il agit en tant qu'utilisateur Loxone authentifié. Il obtient exactement les droits de cet utilisateur — les mêmes pièces, catégories et contrôles que cet utilisateur peut voir et utiliser dans les applications Loxone, ni plus ni moins.

Créez un utilisateur Loxone dédié pour chaque assistant IA et accordez-lui uniquement les droits dont il a besoin. Les assistants IA peuvent mal interpréter une demande ou agir sur le mauvais contrôle, et les autorisations de l'utilisateur connecté sont la seule limite d'accès que le Miniserver applique lui-même — un utilisateur restreint maintient toute erreur dans des limites sûres.

De nombreux assistants ajoutent une seconde limite côté client : vous choisissez quels outils du serveur l'assistant peut utiliser. Les outils sont étiquetés afin qu'un client puisse les regrouper :

• Read — consulter la structure et l'état actuel (trouver des contrôles, lire des valeurs, l'historique, les statistiques). Cela ne modifie rien.

• Write — envoyer des commandes qui modifient quelque chose, comme actionner un contrôle ou définir une valeur.

Les outils de ce serveur sont en lecture ou en écriture ; autoriser uniquement les outils de lecture, par exemple, permet à un assistant de produire un rapport sur l'installation sans pouvoir modifier quoi que ce soit. L'endroit où définir cette limite dépend de l'assistant — consultez ses paramètres de connecteur ou MCP.

Ce qu'un assistant peut faire↑

Le serveur permet à un assistant d'utiliser les blocs de commande qui existent déjà dans votre installation, de deux manières : en lisant leur état et en les commandant. Il s'appuie sur vos pièces, catégories et noms de blocs de commande existants, et ne modifie pas la programmation de l'installation.

Lecture de l'état, de l'historique et des statistiques

Un assistant connecté peut trouver des blocs de commande et lire leurs valeurs actuelles — par exemple si la lumière de la cuisine est allumée, quelle température règne dans une pièce, ou si une porte est ouverte. Il peut également lire l'historique et les statistiques enregistrés, de sorte que vous pouvez poser des questions telles que « quelle a été la température moyenne du salon hier » ou « combien d'énergie la pompe à chaleur a-t-elle consommée la semaine dernière ». Ces requêtes se contentent de lire des informations et ne modifient rien.

Envoi de commandes

L'assistant peut commander les blocs de commande de la même manière que les applications Loxone : allumer ou éteindre une lumière, la varier ou définir une couleur, activer une ambiance lumineuse précise, augmenter ou diminuer une température de consigne, déplacer des stores ou des volets, et déclencher des scènes. Chaque commande est exécutée avec les autorisations de l'utilisateur Loxone connecté.

Certains blocs de commande sont protégés par un mot de passe visu — un mot de passe au niveau du bloc de commande qui protège un bloc de commande individuel, distinct du mot de passe du compte utilisé pour se connecter. Un assistant peut tout de même commander de tels blocs de commande si vous fournissez ce mot de passe visu ; il sert uniquement à autoriser la commande individuelle et n'est jamais stocké ni envoyé à un service cloud.

Ce qui n'est pas pris en charge

Le serveur commande une installation en fonctionnement ; il ne la configure ni ne la reprogramme. Les réglages qui nécessitent des droits élevés — pour lesquels l'application Loxone vous demande de saisir à nouveau le mot de passe de votre compte afin de les déverrouiller — sortent de son champ d'action. Il s'agit d'un mot de passe différent du mot de passe visu au niveau du bloc de commande mentionné ci-dessus, et le serveur ne peut pas effectuer ces actions. Elles comprennent :

• La gestion des utilisateurs — la création ou la modification des utilisateurs, des droits et des autorisations.

• Le mode Expert et les modifications de configuration effectuées dans Loxone Config.

• L'Automatic Designer.

Pour effectuer de telles modifications, utilisez directement l'application Loxone ou Loxone Config.

Trouver votre URL MCP↑

Lorsque vous connectez un assistant comme Claude, vous collez l'adresse du serveur MCP. Elle se termine toujours par /mcp. Il existe deux adresses — l'une pour joindre le Miniserver via Internet et l'autre sur votre réseau local. Choisissez celle qui correspond au mode de connexion de votre assistant.

Via Internet — ouvrez https://connect.loxonecloud.com/<serial> dans un navigateur, en remplaçant <serial> par le numéro de série de votre Miniserver (par exemple https://connect.loxonecloud.com/504F94AABBCC). Votre navigateur est redirigé vers l'adresse .dyndns.loxonecloud.com propre au Miniserver, qui intègre l'IP publique du relais dans le nom. Copiez cette adresse exactement comme elle s'affiche et ajoutez /mcp à la fin.

Sur le réseau local — accédez à l'adresse IP locale du Miniserver (par exemple https://192.168.1.50). Vous êtes redirigé vers son adresse .dyndns.loxonecloud.com, construite de la même façon mais à partir de l'IP locale. Copiez-la et ajoutez /mcp à la fin.

Deux exemples concrets pour un Miniserver avec le numéro de série 504F94AABBCC — adresse publique 203.0.113.42, IP locale 192.168.1.50 :

Ces adresses sont des exemples — copiez l'hôte exact que votre propre navigateur affiche après la redirection.

Pour vérifier les adresses que le plugin annonce effectivement, ouvrez sa page de diagnostic : accédez à https ://<your-miniserver>/dev/sps/io/<uuid>/hello tout en étant authentifié avec un compte Loxone, où <uuid> est l'identifiant de l'objet MCP Server dans Loxone Config. Elle liste les URLs MCP Internet et locales effectives et indique pour chacune s'il s'agit d'une adresse automatique ou d'un remplacement personnalisé.

Connecter votre assistant↑

Les étapes ci-dessous couvrent les assistants les plus courants. Dans chaque cas, collez l'URL MCP indiquée dans "Trouver votre URL MCP" ci-dessus et authentifiez-vous une seule fois avec un compte utilisateur Loxone. Utilisez l'adresse Internet pour les assistants qui s'exécutent dans le cloud (comme claude.ai) et l'adresse locale pour ceux qui fonctionnent sur le même réseau. Les exemples utilisent l'adresse Internet https://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp — remplacez-la par la vôtre.

Les assistants cloud comme claude.ai — et les Connectors de Claude Desktop — se connectent depuis le cloud de l'assistant et atteignent le serveur uniquement en HTTPS standard sur le port 443. Remote Connect publie le Miniserver sur un port non standard, une adresse Remote Connect ne fonctionne donc pas pour ces connexions cloud ; servez le point de terminaison sur le port 443 avec le proxy inverse ou le domaine personnalisé décrit dans "Proxy inverse ou domaine personnalisé" ci-dessous. Les assistants qui exécutent un pont local sur votre propre ordinateur — Local MCP Server de Claude Desktop, Claude Code, LM Studio — peuvent utiliser directement une adresse Remote Connect, sur n'importe quel port. Les assistants sur votre propre réseau peuvent utiliser l'adresse locale, ce qui maintient le trafic sur le LAN.

Claude (claude.ai, dans le navigateur)

Ouvrez Paramètres (Settings) et allez dans Connectors. Choisissez d'ajouter un connecteur personnalisé, donnez-lui un nom comme Loxone, puis collez votre MCP URL Internet se terminant par /mcp. Enregistrez-la, puis ouvrez le connecteur et authentifiez-vous avec votre compte Loxone pour autoriser l'accès. Un Connector s'exécute depuis le cloud de Claude et fonctionne uniquement lorsque votre adresse Internet est accessible en HTTPS standard (port 443). Une adresse Remote Connect utilise un port non standard et ne se connectera pas de cette manière — servez le point de terminaison sur le port 443 avec le proxy inverse ou le domaine personnalisé décrit ci-dessous. Étapes actuelles d'Anthropic

Claude Desktop

Claude Desktop propose deux façons d'ajouter un serveur, et elles se comportent différemment ici. Son paramètre Connectors transmet l'URL au cloud de Claude — le même chemin que claude.ai dans le navigateur — il fonctionne donc uniquement en HTTPS standard (port 443) et pas avec une adresse Remote Connect sur un port non standard. Ajoutez plutôt un Local MCP Server : sous Paramètres (Settings) → Developer, il exécute un petit pont sur votre propre ordinateur, qui peut atteindre le Miniserver sur n'importe quel port, y compris une adresse Remote Connect. Choisissez Edit Config et ajoutez le serveur à claude_desktop_config.json (étapes actuelles d'Anthropic) :

{ "mcpServers" : { "loxone" : { "command" : "npx", "args" : ["mcp-remote", "https ://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp"] } } }

Redémarrez Claude Desktop ; une fenêtre de navigateur s'ouvre pour l'authentification Loxone.

Claude Code (ligne de commande)

Ajoutez le serveur avec le CLI Claude Code :

claude mcp add --transport http loxone https://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp

Exécutez ensuite /mcp dans Claude Code et terminez l'authentification Loxone dans votre navigateur.

LM Studio

Ouvrez l'onglet Program et choisissez Edit mcp.json, puis ajoutez le serveur sous mcpServers avec un champ url :

{ "mcpServers" : { "loxone" : { "url" : "https ://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp" } } }

Enregistrez le fichier ; LM Studio vous invite à vous authentifier avec votre compte Loxone.

Proxy inverse ou domaine personnalisé↑

La plupart des installations n'ont besoin de rien ici — par défaut, le plugin détermine et annonce ses propres adresses. Un proxy inverse ou un domaine personnalisé est surtout nécessaire pour les assistants cloud : les clients comme claude.ai (et les Connectors de Claude Desktop) se connectent en HTTPS standard sur le port 443 avec un certificat publiquement approuvé, tandis que Remote Connect publie le Miniserver sur un port non standard, une adresse Remote Connect ne peut donc pas être utilisée pour eux. Placer le Miniserver derrière un proxy inverse ou un domaine personnalisé qui sert le point de terminaison sur le port 443 (par exemple un tunnel Cloudflare ou nginx) le rend accessible — c'est aussi la voie à suivre si vous voulez simplement utiliser votre propre domaine et certificat.

Lorsque vous en utilisez un, indiquez au plugin quelle adresse publique annoncer. Sinon, l'adresse automatique pointe vers le Miniserver derrière le proxy au lieu du proxy lui-même, et l'authentification échoue.

Le champ à renseigner dépend de la façon dont votre proxy atteint le Miniserver — et non de l'endroit où l'assistant s'exécute :

• URL externe personnalisée — configurez ce champ lorsque votre proxy atteint le Miniserver via son adresse externe (une IP publique ou Remote Connect).

• URL locale personnalisée — configurez ce champ lorsque votre proxy atteint le Miniserver via son adresse locale sur le LAN.

La valeur que vous saisissez est l'URL MCP publique propre au proxy — l'adresse que les assistants collent — par exemple https ://mcp.example.com/mcp. Seules les adresses https sont acceptées. Laissez un champ vide pour conserver l'adresse automatique de ce chemin ; renseignez l'un, l'autre ou les deux.

Le proxy doit transférer l'hôte complet, pas seulement /mcp. Les chemins /mcp et les chemins /.well-known au niveau racine doivent tous atteindre le Miniserver. L'authentification utilise une adresse de découverte à la racine de l'hôte (https ://mcp.example.com/.well-known/oauth-authorization-server/mcp), qui se trouve en dehors de /mcp. Un proxy qui ne transfère que /mcp permet à l'assistant de trouver le serveur, mais pas le service de connexion ; la connexion échoue donc.

Entrées diagnostic↑

Propriétés↑