MCP Server

Il plugin McpServer esegue un server Model Context Protocol (MCP) direttamente sul Miniserver. Consente agli assistenti e agli agenti IA di interrogare lo stato dell'installazione e di inviare comandi ai controlli, usando ambienti, categorie e nomi dei controlli già esistenti — senza un servizio cloud proprio.

L'accesso è protetto dal login Loxone. Un assistente che si collega deve accedere con un account utente Loxone e può vedere e comandare solo ciò per cui tale utente è autorizzato. Creare un utente dedicato con i diritti minimi necessari all'assistente.

Contenuto

• Panoramica
• Configurazione
• Prerequisiti
• Accesso e autorizzazioni
• Cosa può fare un assistente
• Trovare il proprio URL MCP
• Collegare l'assistente
• Reverse proxy o dominio personalizzato
• Ingressi, uscite, proprietà

Panoramica↑

Model Context Protocol (MCP) è uno standard aperto che consente agli assistenti IA di collegarsi a sistemi esterni tramite un insieme ben definito di strumenti. Questo plugin implementa un server MCP per il Miniserver, così un assistente collegato può trovare controlli, leggere il loro stato attuale e attivare comandi senza alcun servizio cloud.

Il server legge la struttura dell'installazione dal Miniserver (ambienti, categorie, controlli) e la presenta all'assistente. Le richieste dell'assistente vengono tradotte negli stessi comandi di controllo usati dalle app Loxone, quindi non è necessaria alcuna configurazione aggiuntiva dei singoli controlli.

Configurazione↑

Aggiungere il plugin McpServer all'installazione e lasciarlo avviare. L'assistente si collega all'URL MCP del plugin — esiste un indirizzo per l'accesso tramite internet e uno per la rete locale. Vedere "Trovare il proprio URL MCP" di seguito per sapere come ottenerli e "Collegare l'assistente" per i passaggi relativi agli assistenti più diffusi. Incollare l'indirizzo adatto all'assistente; al primo collegamento, accedere con un account utente Loxone per concedere l'accesso.

Non sono necessari account di terze parti o servizi esterni. L'assistente si autentica direttamente sul Miniserver e ogni richiesta viene eseguita con le autorizzazioni dell'utente Loxone che ha effettuato l'accesso.

Prerequisiti↑

È richiesto un Miniserver che supporti i plugin (.LxAddOn), insieme a un assistente o agente compatibile con MCP in grado di raggiungere l'endpoint pubblicato e a un account utente Loxone con cui l'assistente possa accedere.

Un assistente può vedere e controllare solo ciò che è consentito al suo utente Loxone. Concedere all'utente dedicato solo i diritti minimi richiesti e revocare l'accesso in qualsiasi momento disattivando tale utente o rimuovendo la connessione.

Accesso e autorizzazioni↑

Quando un assistente si collega, opera come l'utente Loxone che effettua l'accesso. Ottiene esattamente i diritti di tale utente — gli stessi ambienti, categorie e controlli che l'utente può vedere e comandare nelle app Loxone, né di più né di meno.

Creare un utente Loxone dedicato per ogni assistente IA e concedergli solo i diritti necessari. Gli assistenti IA possono interpretare male una richiesta o agire sul controllo sbagliato e le autorizzazioni dell'utente connesso sono l'unico limite di accesso applicato dal Miniserver stesso — un utente limitato mantiene eventuali errori entro limiti sicuri.

Molti assistenti aggiungono un secondo limite lato client: si sceglie quali strumenti del server l'assistente può usare. Gli strumenti sono etichettati in modo che un client possa raggrupparli:

• Read — consulta la struttura e lo stato attuale (trova controlli, legge valori, storico, statistiche). Non modifica nulla.

• Write — invia comandi che modificano qualcosa, ad esempio il comando di un controllo o l'impostazione di un valore.

Gli strumenti di questo server sono di lettura o scrittura; consentire solo gli strumenti di lettura, ad esempio, permette a un assistente di fornire informazioni sull'installazione senza poter modificare nulla. Il punto in cui impostare questo limite dipende dall'assistente — vedere le sue impostazioni del connector o MCP.

Cosa può fare un assistente↑

Il server consente a un assistente di operare con i controlli già presenti nell'installazione in due modi: leggendone lo stato e comandandoli. Utilizza gli ambienti, le categorie e i nomi dei controlli esistenti e non modifica il modo in cui l'installazione è programmata.

Lettura di stato, storico e statistiche

Un assistente collegato può trovare i controlli e leggerne i valori attuali — ad esempio se la luce della cucina è accesa, quanto è caldo un ambiente o se una porta è aperta. Può inoltre leggere lo storico e le statistiche registrate, così è possibile porre domande come "qual è stata la temperatura media del soggiorno ieri" oppure "quanta energia ha consumato la pompa di calore la settimana scorsa". Queste richieste si limitano a leggere informazioni e non modificano nulla.

Invio di comandi

L'assistente può comandare i controlli nello stesso modo in cui lo fanno le app Loxone: accendere o spegnere una luce, regolarne l'intensità o impostare un colore, attivare una specifica atmosfera di illuminazione, aumentare o diminuire una temperatura di riferimento, muovere tapparelle o schermature e attivare scene. Ogni comando viene eseguito con le autorizzazioni dell'utente Loxone connesso.

Alcuni controlli sono protetti da una password visu — una password a livello di controllo che protegge un singolo controllo, distinta dalla password dell'account usata per l'accesso. Un assistente può comandare comunque tali controlli se si fornisce questa password visu; viene usata solo per autorizzare il singolo comando e non viene mai memorizzata né inviata a un servizio cloud.

Cosa non è supportato

Il server comanda un'installazione in funzione; non la configura né la riprogramma. Le impostazioni che richiedono diritti elevati — per le quali l'app Loxone chiede di reinserire la password dell'account per sbloccarle — non rientrano nelle sue funzioni. Si tratta di una password diversa dalla password visu a livello di controllo descritta sopra, e il server non può eseguire queste azioni. Tra queste:

• Gestione utenti — creazione o modifica di utenti, diritti e autorizzazioni.

• La modalità Esperto e le modifiche di configurazione effettuate in Loxone Config.

• Il Designer Automatico.

Per apportare modifiche di questo tipo, usare direttamente l'app Loxone o Loxone Config.

Trovare il proprio URL MCP↑

Quando si collega un assistente come Claude, si incolla l'indirizzo del server MCP. Termina sempre con /mcp. Esistono due indirizzi — uno per raggiungere il Miniserver tramite internet e uno nella rete locale. Scegliere quello che corrisponde al modo in cui si collega l'assistente.

Tramite internet — aprire https://connect.loxonecloud.com/<serial> in un browser, sostituendo <serial> con il numero di serie del Miniserver (ad esempio https://connect.loxonecloud.com/504F94AABBCC). Il browser viene inoltrato all'indirizzo .dyndns.loxonecloud.com proprio del Miniserver, che integra nel nome l'IP del relay pubblico. Copiare l'indirizzo esattamente come mostrato e aggiungere /mcp alla fine.

Nella rete locale — accedere all'indirizzo IP locale del Miniserver (ad esempio https://192.168.1.50). Si viene reindirizzati al suo indirizzo .dyndns.loxonecloud.com, costruito nello stesso modo ma a partire dall'IP locale. Copiarlo e aggiungere /mcp alla fine.

Due esempi pratici per un Miniserver con numero di serie 504F94AABBCC — indirizzo pubblico 203.0.113.42, IP locale 192.168.1.50:

Questi indirizzi sono esempi — copiare l'host esatto mostrato dal proprio browser dopo il reindirizzamento.

Per verificare quali indirizzi il plugin sta effettivamente pubblicando, aprire la sua pagina diagnostica: accedere a https://<your-miniserver>/dev/sps/io/<uuid>/hello mentre si è connessi con un account Loxone, dove <uuid> è l'identificatore dell'oggetto MCP Server in Loxone Config. La pagina elenca gli MCP URLs effettivi per internet e rete locale e indica ciascuno come automatico oppure come override personalizzato.

Collegare l'assistente↑

I passaggi seguenti coprono gli assistenti più comuni. In ogni caso, incollare l'URL MCP da "Trovare il proprio URL MCP" sopra e accedere una volta con un account utente Loxone. Usare l'indirizzo internet per gli assistenti eseguiti nel cloud (come claude.ai) e l'indirizzo locale per gli assistenti eseguiti sulla stessa rete. Gli esempi usano l'indirizzo internet https://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp — sostituirlo con il proprio.

Gli assistenti cloud come claude.ai — e i Connectors di Claude Desktop — si collegano dal cloud dell'assistente e raggiungono il server solo tramite HTTPS standard sulla porta 443. Remote Connect pubblica il Miniserver su una porta non standard, quindi un indirizzo Remote Connect non funziona per questi collegamenti cloud; servire l'endpoint sulla porta 443 con il reverse proxy o il dominio personalizzato descritto in "Reverse proxy o dominio personalizzato" di seguito. Gli assistenti che eseguono un bridge locale sul proprio computer — Local MCP Server di Claude Desktop, Claude Code, LM Studio — possono usare direttamente un indirizzo Remote Connect, su qualsiasi porta. Gli assistenti nella propria rete possono usare l'indirizzo locale, mantenendo il traffico sulla LAN.

Claude (claude.ai, nel browser)

Aprire Impostazioni (Settings) e andare in Connectors. Scegliere di aggiungere un connector personalizzato, assegnargli un nome come Loxone e incollare l'MCP URL internet che termina con /mcp. Salvarlo, quindi aprire il connector e accedere con il proprio account Loxone per autorizzare l'accesso. Un Connector viene eseguito dal cloud di Claude e funziona solo quando il proprio indirizzo internet è raggiungibile su HTTPS standard (porta 443). Un indirizzo Remote Connect usa una porta non standard e non si collegherà in questo modo — servire l'endpoint sulla porta 443 con il reverse proxy o il dominio personalizzato descritto di seguito. Passaggi attuali di Anthropic

Claude Desktop

Claude Desktop offre due modi per aggiungere un server e qui si comportano in modo diverso. La sua impostazione Connectors passa l'URL al cloud di Claude — lo stesso percorso di claude.ai nel browser — quindi funziona solo su HTTPS standard (porta 443) e non con un indirizzo Remote Connect su una porta non standard. Aggiungere invece un Local MCP Server: sotto Impostazioni (Settings) → Developer esegue un piccolo bridge sul proprio computer, che può raggiungere il Miniserver su qualsiasi porta, incluso un indirizzo Remote Connect. Scegliere Edit Config e aggiungere il server a claude_desktop_config.json (passaggi attuali di Anthropic):

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

Riavviare Claude Desktop; si apre una finestra del browser per l'accesso Loxone.

Claude Code (riga di comando)

Aggiungere il server con la CLI Claude Code:

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

Quindi eseguire /mcp in Claude Code e completare l'accesso Loxone nel browser.

LM Studio

Aprire la scheda Program e scegliere Edit mcp.json, quindi aggiungere il server sotto mcpServers con un campo url:

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

Salvare il file; LM Studio richiede di accedere con il proprio account Loxone.

Reverse proxy o dominio personalizzato↑

Nella maggior parte delle installazioni non serve configurare nulla qui — per impostazione predefinita il plugin determina e pubblica i propri indirizzi. Un reverse proxy o un dominio personalizzato è necessario soprattutto per gli assistenti cloud: client come claude.ai (e i Connectors di Claude Desktop) si collegano tramite HTTPS standard sulla porta 443 con un certificato pubblicamente attendibile, mentre Remote Connect pubblica il Miniserver su una porta non standard, quindi un indirizzo Remote Connect non può essere usato per loro. Posizionare il Miniserver dietro un reverse proxy o un dominio personalizzato che serva l'endpoint sulla porta 443 (ad esempio un tunnel Cloudflare o nginx) lo rende raggiungibile — questa è anche la strada da seguire se si desidera semplicemente usare il proprio dominio e certificato.

Quando se ne usa uno, indicare al plugin quale indirizzo pubblico pubblicare. In caso contrario, l'indirizzo automatico punta al Miniserver dietro il proxy anziché al proxy stesso e l'accesso non riesce.

Il campo da compilare dipende da come il proxy raggiunge il Miniserver — non da dove viene eseguito l'assistente:

• URL esterno personalizzato — impostare questo campo quando il proxy raggiunge il Miniserver tramite il suo indirizzo esterno (un IP pubblico o Remote Connect).

• URL locale personalizzato — impostare questo campo quando il proxy raggiunge il Miniserver tramite il suo indirizzo locale sulla LAN.

Il valore inserito è l'URL MCP pubblico proprio del proxy — l'indirizzo che gli assistenti incollano — ad esempio https://mcp.example.com/mcp. Sono accettati solo indirizzi https. Lasciare vuoto un campo per mantenere l'indirizzo automatico per quel percorso; impostarne uno, l'altro o entrambi.

Il proxy deve inoltrare l'intero host, non solo /mcp. Sia i percorsi /mcp sia i percorsi /.well-known a livello root devono raggiungere il Miniserver. L'accesso usa un indirizzo di discovery alla root dell'host (https://mcp.example.com/.well-known/oauth-authorization-server/mcp), che si trova fuori da /mcp. Un proxy che inoltra solo /mcp consente all'assistente di trovare il server ma non il servizio di login, quindi il collegamento non riesce.

Ingressi di diagnosi↑

Proprietà↑