MCP Server

De MCP server plugin voert een Model Context Protocol (MCP) server rechtstreeks op de Miniserver uit. Hiermee kunnen AI-assistenten en agents de status van uw installatie opvragen en commando's naar bedieningselementen sturen, met gebruik van uw bestaande ruimtes, categorieen en namen van bedieningselementen — zonder eigen cloudservice.

Toegang wordt beveiligd door Loxone login. Een assistent die verbinding maakt, moet zich aanmelden met een Loxone gebruikersaccount en kan alleen zien en bedienen waarvoor die gebruiker rechten heeft. Maak een aparte gebruiker aan met de minimale rechten die de assistent nodig heeft.

Inhoudsopgave

• Overzicht
• Instellen
• Vereisten
• Toegang en rechten
• Wat een assistent kan doen
• Uw MCP URL vinden
• Uw assistent verbinden
• Reverse proxy of aangepast domein
• Ingangen, uitgangen, eigenschappen

Overzicht↑

Model Context Protocol (MCP) is een open standaard waarmee AI-assistenten via een duidelijk gedefinieerde set tools verbinding kunnen maken met externe systemen. Deze plugin implementeert een MCP server voor de Miniserver, zodat een verbonden assistent bedieningselementen kan vinden, hun huidige status kan lezen en commando's kan activeren zonder cloudservice.

De server leest de installatiestructuur uit de Miniserver (ruimtes, categorieen, bedieningselementen) en presenteert die aan de assistent. Verzoeken van de assistent worden vertaald naar dezelfde besturingscommando's die de Loxone apps gebruiken, zodat er geen extra configuratie van afzonderlijke bedieningselementen nodig is.

Instellen↑

Voeg de MCP server plugin toe aan de installatie en laat deze starten. Uw assistent maakt verbinding met de MCP URL van de plugin — er is een adres voor toegang via internet en een voor het lokale netwerk. Zie "Uw MCP URL vinden" hieronder om te zien hoe u deze verkrijgt, en "Uw assistent verbinden" voor de stappen voor populaire assistenten. Plak het adres dat bij uw assistent past; de eerste keer dat deze verbinding maakt, meldt u zich aan met een Loxone gebruikersaccount om toegang te verlenen.

Er is geen account van derden of externe service vereist. De assistent authenticeert rechtstreeks bij de Miniserver, en elk verzoek wordt uitgevoerd met de rechten van de Loxone gebruiker die zich heeft aangemeld.

Vereisten↑

Een Miniserver die plugins (.LxAddOn) ondersteunt is vereist, samen met een MCP-compatibele assistent of agent die het gepubliceerde endpoint kan bereiken, en een Loxone gebruikersaccount waarmee de assistent zich kan aanmelden.

Een assistent kan alleen zien en bedienen waarvoor zijn Loxone gebruiker rechten heeft. Geef de aparte gebruiker de minimaal vereiste rechten en trek de toegang op elk moment in door die gebruiker uit te schakelen of de verbinding te verwijderen.

Toegang en rechten↑

Wanneer een assistent verbinding maakt, handelt deze als de Loxone gebruiker die zich aanmeldt. De assistent krijgt exact de rechten van die gebruiker — dezelfde ruimtes, categorieen en bedieningselementen die de gebruiker in de Loxone apps kan zien en bedienen, niet meer en niet minder.

Maak voor elke AI-assistent een aparte Loxone gebruiker aan en geef deze alleen de rechten die nodig zijn. AI-assistenten kunnen een verzoek verkeerd interpreteren of op het verkeerde bedieningselement handelen, en de rechten van de aangemelde gebruiker zijn de enige toegangsbeperking die de Miniserver zelf afdwingt — een beperkte gebruiker houdt elke fout binnen veilige grenzen.

Veel assistenten voegen een tweede limiet aan clientzijde toe: u kiest welke tools van de server de assistent mag gebruiken. Tools zijn gelabeld zodat een client ze kan groeperen:

• Read — zoek structuur en huidige status op (bedieningselementen vinden, waarden lezen, geschiedenis, statistieken). Dit wijzigt niets.

• Write — stuur commando's die iets wijzigen, zoals het bedienen van een bedieningselement of het instellen van een waarde.

De tools van deze server zijn Read of Write; als u bijvoorbeeld alleen Read-tools toestaat, kan een assistent rapporteren over de installatie zonder iets te kunnen wijzigen. Waar u deze limiet instelt, hangt af van de assistent — zie de connector- of MCP-instellingen.

Wat een assistent kan doen↑

De server stelt een assistent in staat om op twee manieren te werken met de bedieningen die al in uw installatie aanwezig zijn: het uitlezen van hun status en het bedienen ervan. Hij maakt gebruik van uw bestaande ruimtes, categorieën en namen van bedieningen, en wijzigt niets aan de manier waarop de installatie is geprogrammeerd.

Status, geschiedenis en statistieken uitlezen

Een verbonden assistent kan bedieningen vinden en hun huidige waarden uitlezen — bijvoorbeeld of het keukenlicht aan is, hoe warm het in een ruimte is, of een deur open staat. Hij kan ook opgeslagen geschiedenis en statistieken uitlezen, zodat u vragen kunt stellen zoals "wat was gisteren de gemiddelde temperatuur in de woonkamer" of "hoeveel energie heeft de warmtepomp vorige week verbruikt". Deze verzoeken lezen alleen informatie uit en wijzigen niets.

Commando's verzenden

De assistent kan bedieningen op dezelfde manier aansturen als de Loxone apps dat doen: een licht in- of uitschakelen, dimmen of een kleur instellen, een specifieke lichtstemming activeren, een streeftemperatuur verhogen of verlagen, jaloezieën of zonwering verstellen en scènes activeren. Elk commando wordt uitgevoerd met de rechten van de aangemelde Loxone-gebruiker.

Sommige bedieningen zijn beveiligd met een visu-wachtwoord — een wachtwoord op bedieningsniveau dat een afzonderlijke bediening beschermt, los van het accountwachtwoord waarmee u zich aanmeldt. Een assistent kan dergelijke bedieningen toch aansturen als u dat visu-wachtwoord opgeeft; het wordt uitsluitend gebruikt om het afzonderlijke commando te autoriseren en wordt nooit opgeslagen of naar een clouddienst verzonden.

Wat niet wordt ondersteund

De server bedient een actieve installatie; hij configureert of herprogrammeert deze niet. Instellingen die verhoogde rechten vereisen — waarbij de Loxone app u vraagt om uw accountwachtwoord opnieuw in te voeren om ze te ontgrendelen — vallen buiten het bereik. Dit is een ander wachtwoord dan het hierboven genoemde visu-wachtwoord op bedieningsniveau, en de server kan deze acties niet uitvoeren. Hiertoe behoren:

• Gebruikersbeheer — het aanmaken of wijzigen van gebruikers, rechten en machtigingen.

• Expertmodus en configuratiewijzigingen die in Loxone Config worden uitgevoerd.

• De Automatic Designer.

Gebruik voor dergelijke wijzigingen rechtstreeks de Loxone app of Loxone Config.

Uw MCP URL vinden↑

Wanneer u een assistent zoals Claude verbindt, plakt u het adres van de MCP server. Dit eindigt altijd op /mcp. Er zijn twee adressen — een om de Miniserver via internet te bereiken en een op uw lokale netwerk. Kies het adres dat past bij de manier waarop uw assistent verbinding maakt.

Via internet — open https://connect.loxonecloud.com/<serial> in een browser en vervang <serial> door het serienummer van uw Miniserver (bijvoorbeeld https://connect.loxonecloud.com/504F94AABBCC). Uw browser wordt doorgestuurd naar het eigen .dyndns.loxonecloud.com-adres van de Miniserver, waarin het openbare relay-IP in de naam is verwerkt. Kopieer dat adres exact zoals weergegeven en voeg /mcp toe aan het einde.

Op het lokale netwerk — ga naar het lokale IP-adres van de Miniserver (bijvoorbeeld https://192.168.1.50). U wordt doorgestuurd naar het .dyndns.loxonecloud.com-adres, dat op dezelfde manier is opgebouwd maar dan vanuit het lokale IP. Kopieer het en voeg /mcp toe aan het einde.

Twee uitgewerkte voorbeelden voor een Miniserver met serienummer 504F94AABBCC — openbaar adres 203.0.113.42, lokaal IP 192.168.1.50:

Deze adressen zijn voorbeelden — kopieer de exacte host die uw eigen browser na de omleiding toont.

Om te controleren welke adressen de plugin daadwerkelijk adverteert, opent u de diagnosepagina: ga naar https://<your-miniserver>/dev/sps/io/<uuid>/hello terwijl u bent aangemeld met een Loxone account, waarbij <uuid> de identificatie is van het MCP Server-object in Loxone Config. De pagina toont de effectieve internet- en lokale MCP URLs en markeert elk adres als automatisch of als aangepaste overschrijving.

Uw assistent verbinden↑

De onderstaande stappen behandelen de meest gebruikte assistenten. In elk geval plakt u de MCP URL uit "Uw MCP URL vinden" hierboven en meldt u zich eenmalig aan met een Loxone gebruikersaccount. Gebruik het internetadres voor assistenten die in de cloud draaien (zoals claude.ai) en het lokale adres voor assistenten die op hetzelfde netwerk draaien. De voorbeelden gebruiken het internetadres https://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp — vervang dit door uw eigen adres.

Cloudassistenten zoals claude.ai — en Claude Desktop's Connectors — maken verbinding vanuit de cloud van de assistent en bereiken de server alleen via standaard HTTPS op poort 443. Remote Connect publiceert de Miniserver op een niet-standaard poort, waardoor een Remote Connect adres niet werkt voor deze cloudverbindingen; bied het endpoint aan op poort 443 met de reverse proxy of het aangepaste domein zoals beschreven in "Reverse proxy of aangepast domein" hieronder. Assistenten die een lokale bridge op uw eigen computer draaien — Claude Desktop's Local MCP Server, Claude Code, LM Studio — kunnen een Remote Connect adres rechtstreeks gebruiken, op elke poort. Assistenten op uw eigen netwerk kunnen het lokale adres gebruiken, waardoor het verkeer op het LAN blijft.

Claude (claude.ai, in de browser)

Open Instellingen (Settings) en ga naar Connectors. Kies om een aangepaste connector toe te voegen, geef deze een naam zoals Loxone en plak uw internet MCP URL die eindigt op /mcp. Sla deze op, open daarna de connector en meld u aan met uw Loxone account om toegang te autoriseren. Een Connector draait vanuit Claude's cloud en werkt alleen wanneer uw internetadres bereikbaar is via standaard HTTPS (poort 443). Een Remote Connect adres gebruikt een niet-standaard poort en zal op deze manier geen verbinding maken — bied het endpoint aan op poort 443 met de hieronder beschreven reverse proxy of aangepast domein. de huidige stappen van Anthropic

Claude Desktop

Claude Desktop biedt twee manieren om een server toe te voegen, en ze gedragen zich hier verschillend. De Connectors-instelling geeft de URL door aan Claude's cloud — hetzelfde pad als claude.ai in de browser — zodat deze alleen werkt via standaard HTTPS (poort 443) en niet met een Remote Connect adres op een niet-standaard poort. Voeg in plaats daarvan een Local MCP Server toe: onder Instellingen (Settings) → Developer draait deze een kleine bridge op uw eigen computer, die de Miniserver op elke poort kan bereiken, inclusief een Remote Connect adres. Kies Edit Config en voeg de server toe aan claude_desktop_config.json (de huidige stappen van Anthropic):

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

Start Claude Desktop opnieuw; er wordt een browservenster geopend voor de Loxone-aanmelding.

Claude Code (opdrachtregel)

Voeg de server toe met de Claude Code CLI:

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

Voer daarna /mcp uit in Claude Code en voltooi de Loxone-aanmelding in uw browser.

LM Studio

Open het tabblad Program en kies Edit mcp.json, voeg vervolgens de server toe onder mcpServers met een url-veld:

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

Sla het bestand op; LM Studio vraagt u zich aan te melden met uw Loxone account.

Reverse proxy of aangepast domein↑

Voor de meeste installaties is hier niets nodig — standaard bepaalt en adverteert de plugin zijn eigen adressen. Een reverse proxy of aangepast domein is vooral nodig voor cloudassistenten: clients zoals claude.ai (en Claude Desktop's Connectors) maken verbinding via standaard HTTPS op poort 443 met een publiek vertrouwd certificaat, terwijl Remote Connect de Miniserver op een niet-standaard poort publiceert, waardoor een Remote Connect adres niet voor hen kan worden gebruikt. Door de Miniserver achter een reverse proxy of aangepast domein te plaatsen dat het endpoint op poort 443 aanbiedt (bijvoorbeeld een Cloudflare tunnel of nginx), wordt hij bereikbaar — dit is ook de route als u simpelweg uw eigen domein en certificaat wilt gebruiken.

Wanneer u er een gebruikt, geeft u de plugin op welk openbaar adres moet worden geadverteerd. Anders wijst het automatische adres naar de Miniserver achter de proxy in plaats van naar de proxy zelf, en mislukt het aanmelden.

Welk veld u invult hangt af van hoe uw proxy de Miniserver bereikt — niet van waar de assistent draait:

• Aangepaste externe URL — stel dit in wanneer uw proxy de Miniserver bereikt via zijn externe adres (een openbaar IP-adres of Remote Connect).

• Aangepaste lokale URL — stel dit in wanneer uw proxy de Miniserver bereikt via zijn lokale adres op het LAN.

De waarde die u invoert is de eigen openbare MCP URL van de proxy — het adres dat assistenten plakken — bijvoorbeeld https://mcp.example.com/mcp. Alleen https-adressen worden geaccepteerd. Laat een veld leeg om het automatische adres voor dat pad te behouden; stel het ene, het andere of beide in.

De proxy moet de volledige host doorsturen, niet alleen /mcp. Zowel de /mcp paden als de root-level /.well-known paden moeten de Miniserver bereiken. Aanmelden gebruikt een discovery-adres op de root van de host (https://mcp.example.com/.well-known/oauth-authorization-server/mcp), dat buiten /mcp ligt. Een proxy die alleen /mcp doorstuurt laat de assistent de server vinden, maar niet de loginservice, waardoor verbinden mislukt.

Diagnose ingangen↑

Eigenschappen↑