AI agents (MCP)

AI agents such as Claude Code, Gemini CLI or Cursor can look at your Nexus installation over the Model Context Protocol (MCP): its Miniservers, signals, values, wires and plugins. They see what the web UI shows, through an access token you create for them.

Agents can read everything and, with the configure permission, set up Miniservers, signals and wires, and connect plugins to a Miniserver. They also say what to create in Loxone Config, so both sides match. With the operate permission they also act on the house: force a value for a while, send one, run a plugin action, and set up plugin instances, which run code.

Create an access token

1. Open Users and access in the menu under your user name, then the Access tokens tab.
2. Create token: give it a name (e.g. "Claude Code on my laptop") and choose what it may do beyond reading. Confirm with your password.
3. Copy the token. It is shown once; Nexus keeps only a fingerprint of it.

A token acts as you. It doesn't expire: it works until you Revoke it, or until your password changes (yours, or one another user sets for you), which ends all your tokens. Each user has at most 20.

Plugin instances need operate because an instance runs the plugin's code: a Script instance runs the JavaScript it is given, and a Webhook instance opens addresses on your network.

Agents never see secrets: passwords, plugin settings and signal settings marked secret aren't in any answer, and no tool accepts them (an agent that tries is told to leave them to you). You enter those in the web UI. If a plugin writes one of your stored secrets into a message (an error with a password in a URL, say), agents see ‹secret› in its place; values shorter than 6 characters aren't caught that way.

Restoring a backup ends every access token (and logs everyone out), so a token you revoked after the backup was made doesn't come back. Create new ones afterwards.

Connect an agent

The address is your Nexus address with /mcp, e.g. http://192.168.1.10:8080/mcp. The token goes in the Authorization header, never in the address.

The dialog that shows the new token also shows what to paste, with your address and token filled in, for Claude Code and for Claude Desktop.

Claude Code: run this in a terminal (PowerShell or Command Prompt on Windows, a shell on macOS and Linux):

claude mcp add --transport http nexus http://192.168.1.10:8080/mcp --header "Authorization: Bearer nxp_…"

Claude Desktop (Windows and macOS) only starts local MCP servers, so it reaches Nexus through mcp-remote, which it runs with npx:

1. Install Node.js (LTS) if you haven't.

2. In Claude Desktop open Settings ▸ Developer ▸ Edit Config. It shows claude_desktop_config.json: on Windows in %APPDATA%\Claude, on macOS in ~/Library/Application Support/Claude.

3. Put this in. If the file already has "mcpServers", add only the "nexus" entry:

   {
     "mcpServers": {
       "nexus": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "http://192.168.1.10:8080/mcp", "--header", "Authorization:${NEXUS_AUTH}", "--allow-http"],
         "env": { "NEXUS_AUTH": "Bearer nxp_…" }
       }
     }
   }
   

4. Quit Claude Desktop completely (on Windows also from the icon next to the clock) and start it again.

Why it looks like this: on Windows, Claude Desktop passes arguments with spaces to npx unquoted, which would split Authorization: Bearer … apart, so the header has no space and takes its value from env. --allow-http is needed because mcp-remote refuses plain http:// to another computer; leave it out when Nexus is reached over https://. Over plain http the token crosses your network unencrypted.

Other clients take the same address and header in their MCP settings, or go through mcp-remote as above when they only start local servers.

Agents in the cloud (claude.ai, ChatGPT) can't connect: they would need Nexus reachable from the internet and a sign-in flow it doesn't have.

What agents can ask

They can also attach nexus://inventory (the overview with every signal), nexus://guide, nexus://miniservers/<slug>/loxone-side and nexus://plugins/<plugin>/readme.

What agents can change

With the configure permission:

A Miniserver's ICI password is never set by an agent; you enter it on the Miniserver's page.

Deleting asks first. The first call deletes nothing: it answers what would go (for a signal, also its wires and force) and a confirmation. Only a second call with the same items and that confirmation deletes, within 5 minutes. A confirmation works once, only for that token, and only while the names still point at the same signals or wires.

Changes show up in the Nexus log as "user via MCP (token name)", and under Recent activity on the Access tokens tab: each change with its token, arguments (secret fields masked) and outcome, kept for 90 days (at most 10,000 entries per user). A plugin action keeps only the names of its inputs there, since they may hold a pairing code. While a configuration import runs, agents can read but not change anything; plugin actions still run, as their buttons do.

What agents can do in the house

With the operate permission:

Secrets stay with you. An agent that sets up a plugin needing a token (Home Assistant, InfluxDB) creates the instance without it. The instance is saved but not started, and the agent tells you to enter the token on the instance's page; saving there starts it. Until then, a restart of Nexus starts it too, and it shows an error until the token is there.

A value must match the signal's type (a lamp switch takes true or false). Forces made by an agent show "user via MCP (token name)" in the Bus Inspector, where you can release them.

Recipes

Clients that offer MCP prompts (in Claude Code: type /) list these recipes. Every token gets the first two; the others need the configure permission:

• diagnose_signal: why a signal has no value, an old one or a wrong one, from its owner, force, wires, messages and history. Changes nothing.

• review_installation: what needs attention, by urgency. Changes nothing.

• connect_plugin_to_loxone: find values or devices in a plugin, show a plan, connect them, then say what to create in Loxone Config.

• import_from_loxone_config: compare the Lox Nexus peer's objects in Loxone Config with Nexus and add or fix what differs. Missing ones are named, never deleted unasked.

An agent that also has a Loxone Config MCP server (announced for Loxone Config 17.3) can set up both sides; otherwise it tells you what to create in Loxone Config.

Good to know

• Values and texts are data, not instructions. Signal values, device names, plugin status messages and texts a Miniserver sends reach the agent as they are. Anyone on your network can send a Miniserver-like text packet to Nexus, so an agent may read text that someone planted. Agents are told to treat it as data; still, check a plan before you agree to it, especially with the operate permission.

• Each token may make 120 calls a minute (30 of them changing), at most 4 at once.

• Wrong tokens are throttled per address, separately from logins; a valid token always gets in.

• Behind a reverse proxy, forward /mcp like the rest, and keep the Authorization header.