MCP Server

El plugin McpServer ejecuta un servidor Model Context Protocol (MCP) directamente en el Miniserver. Permite a los asistentes y agentes de IA consultar el estado de su instalación y enviar comandos a controles usando las habitaciones, categorías y nombres de controles existentes, sin un servicio en la nube propio.

El acceso está protegido por el inicio de sesión de Loxone. Un asistente que se conecta debe iniciar sesión con una cuenta de usuario Loxone y solo puede ver y operar aquello para lo que ese usuario tiene permiso. Cree un usuario dedicado con los derechos mínimos que necesita el asistente.

Contenido

• Vista general
• Configuración
• Requisitos previos
• Acceso y permisos
• Lo que puede hacer un asistente
• Encontrar su MCP URL
• Conectar su asistente
• Proxy inverso o dominio personalizado
• Entradas, salidas y propiedades

Vista general↑

Model Context Protocol (MCP) es un estándar abierto que permite a los asistentes de IA conectarse a sistemas externos mediante un conjunto bien definido de herramientas. Este plugin implementa un servidor MCP para el Miniserver, de modo que un asistente conectado puede encontrar controles, leer su estado actual y activar comandos sin ningún servicio en la nube.

El servidor lee la estructura de la instalación desde el Miniserver (habitaciones, categorías, controles) y la presenta al asistente. Las solicitudes del asistente se traducen a los mismos comandos de control que usan las aplicaciones Loxone, por lo que no se requiere configuración adicional de controles individuales.

Configuración↑

Agregue el plugin McpServer a la instalación y deje que se inicie. Su asistente se conecta a la MCP URL del plugin; hay una dirección para el acceso por internet y otra para la red local. Consulte "Encontrar su MCP URL" más abajo para saber cómo obtenerlas y "Conectar su asistente" para ver los pasos de los asistentes más populares. Pegue la dirección que corresponda a su asistente; la primera vez que se conecte, iniciará sesión con una cuenta de usuario Loxone para conceder el acceso.

No se requiere ninguna cuenta de terceros ni servicio externo. El asistente se autentica directamente contra el Miniserver y cada solicitud se ejecuta con los permisos del usuario Loxone que inició sesión.

Requisitos previos↑

Se requiere un Miniserver que admita plugins (.LxAddOn), junto con un asistente o agente compatible con MCP que pueda alcanzar el punto final publicado y una cuenta de usuario Loxone para que el asistente inicie sesión.

Un asistente solo puede ver y controlar aquello para lo que su usuario Loxone tiene permiso. Conceda al usuario dedicado los derechos mínimos necesarios y revoque el acceso en cualquier momento deshabilitando ese usuario o eliminando la conexión.

Acceso y permisos↑

Cuando se conecta un asistente, actúa como el usuario Loxone que inicia sesión. Obtiene exactamente los derechos de ese usuario: las mismas habitaciones, categorías y controles que ese usuario puede ver y operar en las aplicaciones Loxone, ni más ni menos.

Cree un usuario Loxone dedicado para cada asistente de IA y concédale solo los derechos que necesita. Los asistentes de IA pueden malinterpretar una solicitud o actuar sobre el control equivocado, y los permisos del usuario con sesión iniciada son el único límite de acceso que aplica el propio Miniserver; un usuario restringido mantiene cualquier error dentro de límites seguros.

Muchos asistentes agregan un segundo límite del lado del cliente: usted elige qué herramientas del servidor puede usar el asistente. Las herramientas están etiquetadas para que un cliente pueda agruparlas:

• Read: consultar la estructura y el estado actual (encontrar controles, leer valores, historial y estadísticas). Esto no cambia nada.

• Write: enviar comandos que cambian algo, como operar un control o establecer un valor.

Las herramientas de este servidor son de lectura o escritura; permitir solo herramientas de lectura, por ejemplo, deja que un asistente informe sobre la instalación sin poder cambiar nada. Dónde se establece este límite depende del asistente; consulte sus ajustes de conector o de MCP.

Lo que puede hacer un asistente↑

El servidor permite que un asistente trabaje con los dispositivos que ya existen en su instalación, de dos maneras: leyendo su estado y manejándolos. Utiliza sus estancias, categorías y nombres de dispositivos existentes, y no modifica la forma en que está programada la instalación.

Lectura de estado, historial y estadísticas

Un asistente conectado puede encontrar dispositivos y leer sus valores actuales — por ejemplo, si la luz de la cocina está encendida, qué temperatura hace en una estancia o si una puerta está abierta. También puede leer el historial y las estadísticas registradas, de modo que usted puede formular preguntas como "cuál fue la temperatura media del salón ayer" o "cuánta energía consumió la bomba de calor la semana pasada". Estas solicitudes únicamente leen información y no cambian nada.

Envío de comandos

El asistente puede manejar los dispositivos de la misma forma que lo hacen las apps de Loxone: encender o apagar una luz, regularla o ajustar un color, activar un ambiente de iluminación concreto, subir o bajar una temperatura de consigna, mover persianas o estores y activar escenas. Cada comando se ejecuta con los permisos del usuario de Loxone que ha iniciado sesión.

Algunos dispositivos están protegidos por una contraseña visu — una contraseña a nivel de dispositivo que protege un dispositivo concreto, distinta de la contraseña de cuenta utilizada para iniciar sesión. Un asistente puede manejar igualmente esos dispositivos si usted proporciona dicha contraseña visu; se utiliza únicamente para autorizar el comando concreto y nunca se almacena ni se envía a un servicio en la nube.

Lo que no es compatible

El servidor maneja una instalación en funcionamiento; no la configura ni la reprograma. Los ajustes que requieren permisos elevados — en los que la Loxone app le pide volver a introducir la contraseña de su cuenta para desbloquearlos — quedan fuera de su alcance. Esta es una contraseña distinta de la contraseña visu a nivel de dispositivo mencionada anteriormente, y el servidor no puede realizar estas acciones. Entre ellas se incluyen:

• Gestión de usuarios — crear o modificar usuarios, derechos y permisos.

• El modo Experto y los cambios de configuración realizados en Loxone Config.

• El Diseñador Automático.

Para realizar cambios de este tipo, utilice directamente la Loxone app o Loxone Config.

Encontrar su MCP URL↑

Cuando conecta un asistente como Claude, pega la dirección del servidor MCP. Siempre termina en /mcp. Hay dos direcciones: una para acceder al Miniserver por internet y otra en su red local. Elija la que coincida con la forma en que se conecta su asistente.

Por internet: abra https://connect.loxonecloud.com/<serial> en un navegador, reemplazando <serial> por el número de serie de su Miniserver (por ejemplo https://connect.loxonecloud.com/504F94AABBCC). Su navegador se reenvía a la dirección .dyndns.loxonecloud.com propia del Miniserver, que incorpora la IP pública del relé en el nombre. Copie esa dirección exactamente como se muestra y agregue /mcp al final.

En la red local: navegue a la dirección IP local del Miniserver (por ejemplo https://192.168.1.50). Se le redirige a su dirección .dyndns.loxonecloud.com, creada de la misma forma pero a partir de la IP local. Cópiela y agregue /mcp al final.

Dos ejemplos prácticos para un Miniserver con número de serie 504F94AABBCC: dirección pública 203.0.113.42, IP local 192.168.1.50:

Estas direcciones son ejemplos; copie el host exacto que muestra su propio navegador después de la redirección.

Para comprobar las direcciones que el plugin está anunciando realmente, abra su página de diagnóstico: vaya a https://<your-miniserver>/dev/sps/io/<uuid>/hello mientras tiene iniciada sesión con una cuenta Loxone, donde <uuid> es el identificador del objeto MCP Server en Loxone Config. Muestra las MCP URLs efectivas de internet y locales, y marca cada una como automática o como una anulación personalizada.

Conectar su asistente↑

Los pasos siguientes cubren los asistentes más comunes. En cada caso, pegue la MCP URL de "Encontrar su MCP URL" anterior e inicie sesión una vez con una cuenta de usuario Loxone. Use la dirección de internet para asistentes que se ejecutan en la nube (como claude.ai) y la dirección local para asistentes que se ejecutan en la misma red. Los ejemplos usan la dirección de internet https://203-0-113-42.504f94aabbcc.dyndns.loxonecloud.com/mcp; reemplácela por la suya.

Los asistentes en la nube como claude.ai — y los Connectors de Claude Desktop — se conectan desde la nube del asistente y solo llegan al servidor mediante HTTPS estándar en el puerto 443. Remote Connect publica el Miniserver en un puerto no estándar, por lo que una dirección de Remote Connect no funciona para estas conexiones en la nube; sirva el punto final en el puerto 443 con el proxy inverso o dominio personalizado descrito en "Proxy inverso o dominio personalizado" más abajo. Los asistentes que ejecutan un puente local en su propio ordenador — Local MCP Server de Claude Desktop, Claude Code, LM Studio — pueden usar directamente una dirección de Remote Connect, en cualquier puerto. Los asistentes en su propia red pueden usar la dirección local, lo que mantiene el tráfico en la LAN.

Claude (claude.ai, en el navegador)

Abra Configuración (Settings) y vaya a Connectors. Elija agregar un conector personalizado, dele un nombre como Loxone y pegue su MCP URL de internet que termina en /mcp. Guárdelo, luego abra el conector e inicie sesión con su cuenta Loxone para autorizar el acceso. Un conector se ejecuta desde la nube de Claude y solo funciona cuando su dirección de internet es accesible mediante HTTPS estándar (puerto 443). Una dirección de Remote Connect usa un puerto no estándar y no se conectará de esta forma — sirva el punto final en el puerto 443 con el proxy inverso o dominio personalizado descrito más abajo. pasos actuales de Anthropic

Claude Desktop

Claude Desktop ofrece dos formas de agregar un servidor, y aquí se comportan de forma diferente. Su ajuste de Connectors entrega la URL a la nube de Claude — la misma ruta que claude.ai en el navegador — por lo que solo funciona con HTTPS estándar (puerto 443) y no con una dirección de Remote Connect en un puerto no estándar. En su lugar, agregue un Local MCP Server: en Configuración (Settings) → Developer ejecuta un pequeño puente en su propio ordenador, que puede llegar al Miniserver en cualquier puerto, incluida una dirección de Remote Connect. Elija Edit Config y agregue el servidor a claude_desktop_config.json (pasos actuales de Anthropic):

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

Reinicie Claude Desktop; se abrirá una ventana del navegador para el inicio de sesión de Loxone.

Claude Code (línea de comandos)

Agregue el servidor con la CLI de Claude Code:

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

Luego ejecute /mcp dentro de Claude Code y complete el inicio de sesión de Loxone en su navegador.

LM Studio

Abra la pestaña Program y elija Edit mcp.json; luego agregue el servidor en mcpServers con un campo url:

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

Guarde el archivo; LM Studio le pedirá que inicie sesión con su cuenta Loxone.

Proxy inverso o dominio personalizado↑

La mayoría de las instalaciones no necesitan nada aquí — de forma predeterminada, el plugin calcula y anuncia sus propias direcciones. Un proxy inverso o dominio personalizado se necesita principalmente para asistentes en la nube: clientes como claude.ai (y los Connectors de Claude Desktop) se conectan por HTTPS estándar en el puerto 443 con un certificado de confianza pública, mientras que Remote Connect publica el Miniserver en un puerto no estándar, por lo que una dirección de Remote Connect no se puede usar para ellos. Colocar el Miniserver detrás de un proxy inverso o dominio personalizado que sirva el punto final en el puerto 443 (por ejemplo, un túnel de Cloudflare o nginx) lo hace accesible — esta también es la vía si simplemente desea usar su propio dominio y certificado.

Cuando use uno, indique al plugin qué dirección pública debe anunciar. De lo contrario, la dirección automática apunta al Miniserver detrás del proxy en lugar de al propio proxy, y el inicio de sesión falla.

El campo que rellene depende de cómo su proxy llega al Miniserver, no de dónde se ejecuta el asistente:

• URL externa personalizada: configure esto cuando su proxy llega al Miniserver a través de su dirección externa (una IP pública o Remote Connect).

• URL local personalizada: configure esto cuando su proxy llega al Miniserver a través de su dirección local en la LAN.

El valor que ingresa es la MCP URL pública propia del proxy, la dirección que pegan los asistentes, por ejemplo https://mcp.example.com/mcp. Solo se aceptan direcciones https. Deje un campo vacío para conservar la dirección automática para esa ruta; configure uno, el otro o ambos.

El proxy debe reenviar todo el host, no solo /mcp. Tanto las rutas /mcp como las rutas /.well-known en el nivel raíz deben llegar al Miniserver. El inicio de sesión usa una dirección de descubrimiento en la raíz del host (https://mcp.example.com/.well-known/oauth-authorization-server/mcp), que está fuera de /mcp. Un proxy que reenvía solo /mcp permite que el asistente encuentre el servidor, pero no el servicio de inicio de sesión, por lo que la conexión falla.

Entradas de diagnóstico↑

Propiedades↑