AI clients and your own tools

Iris serves the gateway to outside AI clients, such as Claude Desktop or Claude Code, over the Model Context Protocol (MCP). The client brings its own model; Nexus calls none. This page covers what that gives you beyond reading, and how to add tools of your own. Setting up the endpoint, issuing keys and connecting a client is in AI clients (Iris MCP).

What an MCP client can do

	Needs
Read the plant: tags, history, alarms, devices, logs, projects, screens	Nothing extra: read-only MCP is free
Propose a tag write or a project change	A key with Writes on, the mcp license module, and restricted tag access
Use your own tools	The mcp license module

A key acts as a role: it can do what that role can do, and a tool it may not use is absent from what the client is told, and answers like one that does not exist. A key can be narrowed to a few tools but never widened past its role. Even a key with Writes only files proposals; a person approves them (Approvals). Every call is in the audit log under key:<name>.

Your own tools

An integrator can add tools in Python. They are served over MCP and also offered to Iris chat and agents by name. A tool is a project resource: a description, an input schema and a handler, so it travels with the project.

In Studio, open the Project Browser and add one under MCP Tools. The editor has a Test button that calls it as you.

Field	Rule
name	Lower-case letters, digits and _, up to 48. It cannot be the name of a built-in tool.
description	What the model reads to decide when to use it.
class	read or propose. There is no class that writes.
inputSchema	A JSON schema for the arguments. Keywords Nexus does not enforce ($ref, oneOf, pattern) are errors, not ignored.
timeoutMs and maxResultBytes	100 to 10,000 ms; up to 256 KB.
source	Python that defines def handle(args, raylux): and returns a value that can be turned into JSON.

A tool with an invalid definition, or a handler that fails the checks, is not offered; it is shown disabled with the reason. A change to the project applies within about a second, with no restart.

What a handler can and cannot do

A handler runs in the strictest script mode, with a time limit. Its one way to reach the gateway is the raylux argument, whose methods are the built-in read tools (and, for a propose tool, propose_tag_write and propose_resource_change). Each call is made as whoever called the tool, never as the person who wrote it, so it passes the same permission, license and scope checks as if that caller had made it, and each is an audit row. A key scoped to specific tools therefore needs the built-in tools its handler uses in its scope too. A handler can make at most 50 such calls per run.

It has no tag write, no network, no files and no other tool.

This is not a security boundary against hostile code

Python running inside Nexus cannot be locked down completely. The checks stop the easy ways out and make mistakes fail loudly, but they do not stop native code, memory exhaustion or a flaw in Python itself. The real protection is that a handler holds no authority of its own. Let only people you trust author tools, as you would for any gateway script.

Rules

• A read tool needs only the runtime-access capability.
• A propose tool needs AI Use as well, a key with Writes on, and restricted tag access, checked live.
• Authoring a read tool needs Designer access. Authoring a propose tool needs Iris administration as well.
• The mcp license module is needed for every one of your own tools; the built-in read tools stay free.