AI clients (Iris MCP)

Raylux Iris lets an AI client read this gateway over the Model Context Protocol (MCP). Claude Desktop, Claude Code and any other MCP client can ask about tags, alarms, history, devices and projects in plain language. The client brings its own model: Nexus never talks to a model and ships none.

It is read-only. Nothing an AI client can do through Iris writes a tag, acknowledges an alarm or changes configuration, and read-only use needs no AI licence.

What is read leaves the gateway

Whatever an AI client reads is sent to the model that client uses, which may be a cloud service. Issue keys only to clients you trust with this plant's data. Iris is decision support, not a safety function.

Turning it on

The MCP server is off on every new install. Nothing is served until an administrator both turns it on and issues a key.

1. Sign in to the Nexus web page as an administrator (the Iris administration capability, AiAdmin; the built-in Admin role has it).
2. Open Security › Iris MCP.
3. Under MCP server, click Turn on.

It takes effect immediately; no restart. The page shows the Endpoint clients connect to.

Issuing a key

Under New key:

• Name: who holds it, for example Claude Desktop — control room. It appears in the audit log as key:<name>.
• Role: the key acts with that role's capabilities, checked on every call. You cannot give a key more authority than your own.
• Tools: leave it on every tool the role allows, or narrow it to a few. A key's tool list can narrow its role, never widen it.
• Writes: stays off. This release has no write or approval tools.

Click Create key. The key is shown once: copy it before you close the notice. Nexus stores only a hash and cannot show it again, so a lost key is revoked and replaced. Disable stops a key for a while; Revoke removes it.

Which role a key needs:

The client should be able to	Capability
Browse, search and read tags; list active alarms and the alarm journal; list projects, their resources, screens and named queries	Runtime access
Query history	Query history, and the Historian module
List devices and read gateway diagnostics	Device status
Read project scripts and SQL	Designer access
Read the Nexus log	Nexus configuration
Read the audit log	Nexus configuration and Audit log access

The built-in Viewer or Operator role covers most use. A tool the key cannot use is not merely refused: it is left out of what the client is told exists.

Connecting a client

The endpoint is https://<gateway>:8443/api/mcp (MCP Streamable HTTP). The key is sent as Authorization: Bearer rlx_….

Claude Code (and other clients that speak Streamable HTTP) take the URL and the header directly, for example in an .mcp.json:

{
  "mcpServers": {
    "raylux": {
      "type": "http",
      "url": "https://gateway:8443/api/mcp",
      "headers": { "Authorization": "Bearer rlx_…" }
    }
  }
}

Clients that only speak MCP over stdio connect through a bridge such as mcp-remote, given the same URL and header.

HTTPS and the gateway certificate

Keys are refused over plain HTTP (port 8080), before the key is even read: a key sniffed off a plant network is a standing credential. A gateway with tlsDisable or dev mode set has decided TLS is handled elsewhere, and accepts plain HTTP.

Unless you installed your own certificate (see Certificates and HTTPS), the gateway's certificate is self-signed, and a client on another machine must be told to trust it. For Node-based clients (Claude Code, mcp-remote), point NODE_EXTRA_CA_CERTS at the gateway's certs/nexus.crt.

Gateways installed before 2026.20: regenerate the certificate

Certificates generated before 2026.20 name no host (no subjectAltName), and MCP clients refuse them with ERR_TLS_CERT_ALTNAME_INVALID even when told to trust them. Stop Nexus, delete certs/nexus.crt and certs/nexus.key from its data directory, and start it again: it generates a certificate for localhost, 127.0.0.1 and the machine's name. Nexus logs the new certificate's SHA-256 fingerprint at startup; Studio asks once to trust it. A certificate you installed yourself is not affected.

Browser-based clients

Desktop and command-line clients send no Origin header and need nothing here. A client that runs in a web browser does, and is refused unless its origin (for example https://claude.ai) is listed under Allowed browser origins.

What a client can call

Tool	Reads
list_tags, search_tags, read_tags	The tag tree, and live values with quality and timestamp. read_tags also gives a tag's engineering unit and range, and its alarm limits.
query_history	A tag's samples, or min/max/avg buckets over a window.
list_active_alarms	Active and unacknowledged alarms, each with the limit that tripped and the tag's current value.
query_alarm_journal	Alarm history.
list_devices, get_gateway_diagnostics	Device connections and gateway health.
read_logs, query_audit_log	The Nexus log and the audit log.
list_projects, list_project_resources, get_screen, get_project_resource, list_named_queries	HMI projects, screens, scripts and named queries (listed, not run).

Prompts a client can start from: diagnose_alarm, commissioning_sweep and explain_screen. Projects, screens and the tag tree are also offered as MCP resources.

Every result is capped in size and long lists come in pages, so a client browses a big plant rather than downloading it. Plant text such as alarm messages is returned as data, never as instructions.

Auditing

Every call is written to the audit log as AI_TOOL_CALL under the key's name, including a refused call and why. Creating, disabling, enabling and revoking keys (MCP_KEY_CREATE, MCP_KEY_DISABLE, MCP_KEY_ENABLE, MCP_KEY_REVOKE), changing the settings (MCP_SETTINGS_UPDATE), an unknown key (MCP_AUTH_FAILURE), a key sent over plain HTTP (MCP_CLEARTEXT_REFUSED) and a refused browser origin (MCP_ORIGIN_REFUSED) are recorded too.

Limits

• AI calls run on Iris's own worker pool, never on the threads that scan devices, evaluate alarms or record history. When it is full, a call fails with BUSY and the client retries: AI slowing down never slows the plant down.
• One key may have at most 8 calls in flight at once, so one busy client cannot crowd out the others.
• Each call has a deadline, and each response a size cap.

Troubleshooting

The client reports	Cause
ERR_TLS_CERT_ALTNAME_INVALID	A certificate from before 2026.20; regenerate it (above).
Certificate not trusted / self-signed	Point NODE_EXTRA_CA_CERTS at the gateway's certs/nexus.crt.
403, TLS required	The key was sent over http://…:8080; use https://…:8443.
401	Unknown, revoked or disabled key.
503	The MCP server is turned off (Security › Iris MCP › Turn on).
A tool call fails with BUSY	Iris's workers, or this key's 8 calls in flight, are full; retry.
A tool is missing	The key's role or tool list does not include it.