AI Clients (MCP)

CONNECT exposes a Model Context Protocol endpoint. An AI assistant that supports MCP can read signals and inspect the configuration. When allowed, it can also operate the running HMI. All these operations use one endpoint and one URL:

http://localhost:5100/mcp

Use Copy Endpoint URL in the tray menu to copy this URL.

The server is part of the gateway process. It requires no second program, Node.js installation or build step. The same executable that talks to your PLC answers the AI client.

What the tools cover

Two families share the endpoint:

Gateway tools - signals, interfaces, status. Available whenever the gateway runs.
Browser tools - the web_* tools of the running realvirtual session: scene, components, simulation, layout, editor. They appear when a browser is connected with AI control on. They disappear when it closes or AI control is switched off. Connected clients are notified of the change.

While the viewer tab has AI control off (Settings ▸ AI), the client sees only the gateway tools plus web_status and web_call_pending. web_status then answers aiEnabled: false with a hint. Any other web_* call is refused with an error that starts with AI_DISABLED:, including calls from clients on the same PC. Do not retry such a call; switch AI control on in that tab.

This is why the endpoint is same-origin with the HMI: the AI reaches the delivered viewer as it actually runs.

Tool availability depends on write access and the viewer tab’s AI control setting.

Gateway tools

These eight are CONNECT’s own and never depend on a browser. The four write tools are announced only while write access is on.

Tool	Access	What it does
`signal_list`	read	Lists every signal with type, value and force state
`signal_read`	read	Reads one signal by name
`interfaces_status`	read	Live status of every configured interface, including the active profile
`health`	read	MCP and signal-store health, plus the state of both MCP switches
`signal_set_bool`	write	Sets a boolean signal
`signal_set_float`	write	Sets a floating-point signal
`signal_force`	write	Forces a signal to a fixed value until it is released
`signal_unforce`	write	Releases a forced signal

When the switch refuses a write, the response names the switch. The assistant can then tell the operator what to do rather than retrying. Writes also require a valid license. If it has expired, they return LICENSE_REQUIRED. Writes that reach a PLC are still governed per interface by AllowWebToPlc. This endpoint neither reads nor overrides that setting.

Browser tools

The viewer announces everything it can do while a browser is connected. Different viewer versions announce different tool sets, so the client’s tool list is the reference for the current session.

Names follow web_<domain>_<action>. The domains, and what each is for:

Domain	What it covers
`web_*` (unprefixed)	Orientation and diagnosis: status, console log, current alarms, workflow guides, distance measurement between parts, an offscreen render from any camera pose, and a liveness probe — plus the command interface: `web_commands` lists the viewer’s commands, `web_execute` runs one, `web_batch` runs several in one call
`macro`	Recording model changes as a replayable macro with a reason per step, replaying it as a job, and adding geometry assertions
`check`	Mesh-exact gap and contact between two parts, optionally in a given drive pose
`part`	Looking up a drive’s stroke and moving sub-parts from its type code
`node`	Searching the scene graph, reading its structure, bounds and the shape of a part — the source of the node paths every other tool takes
`component`	Reading and writing component configuration
`select` / `selection`	Selecting parts exactly as a user click does, selecting similar parts, and reading what is selected
`view`	Pointing at things, isolating them, overlays, and a multi-view contact sheet of an unknown assembly
`camera`	Driving the real viewport camera: position, focus, orbit, fly-through, perspective or orthographic
`screenshot`	A single frame, a motion montage, a labelled frame with markers, and a four-view shape analysis
`drive`	Listing drives, jogging and stopping them, overriding their speed
`signal`	Listing signals, reading their state, writing values — and binding or unbinding them to component slots
`sensor`	Listing sensors and what they currently detect
`sim`	Playing, pausing and resetting the simulation
`transport`	The state of the transport surfaces and what is riding on them
`logic`	The logic sequence driving the model
`document`	The document family: listing every document of the project, opening one, saving, creating and renaming
`project`	Which project the project-relative paths resolve against, and navigating its folder tree
`mode`	Switching the workspace mode
`editor`	Asset authoring — by a wide margin the largest domain: structure, transforms, pivots, kinematics, mechanisms, materials, signals, undo and save
`layout`	Building layouts: placing, moving and removing objects, and attaching them at their snap points
`catalog`	The parts catalog of the Layout Planner — placeable templates, not project documents
`knowledge`	Notes an assistant leaves on a node, stored inside the document
`des`	Discrete event simulation: status, statistics, bottlenecks, stepping
`plc`	The virtual PLC: deploy, run, stop, status
`scene`	A read-only query over a frozen scene snapshot — the escape hatch for questions no dedicated tool answers
`link`	Composing a shareable deep link to what is currently open

As of October 2026 that is 209 tools across 28 domains. The number changes with the viewer, so use the client’s tool list as the current reference.

New modelling capabilities arrive as commands rather than new tools. web_commands always shows the current set, with each command’s arguments and whether it is read-only. web_execute / web_batch run them. The older per-action editor tools keep working.

web_help(topic) returns the guide for a workflow: editor, kinematize, layout, simulation, plc, des, commands, macros. Read the matching one before starting a multi-step job.

The full reference is delivered, not looked up

There is no reference to install or keep in sync. When a client connects, the gateway sends the complete, generated tool reference as the MCP server’s instructions. The assistant has the full tool list and workflow rules from the first message. The same file ships with the viewer sources as webviewer.mcp.md.

What to ask for

The tools are low-level on purpose; the workflows are not. Three that are worth knowing because they are what the tool set was built for:

Turn a raw CAD import into a moving machine.

Open the imported assembly in the Editor, work out what this machine does, give the parts speaking names, assign industrial materials, then build the kinematic axes with drives and verify each one by jogging it.

Before changing the model, the assistant examines a contact sheet of views and a part’s shape and rotation axis. It verifies every axis by moving it, following web_help("kinematize").

Build a conveyor line in the Layout Planner.

Switch to Planner mode, place a feed conveyor, two buffer sections and a turntable from the catalog, and connect them into one line at the correct transfer height.

Objects are placed from the catalog and joined at their snap points, so the result is a connected line rather than geometry that happens to touch.

Make a modelling session repeatable.

Record a macro while you fix the stopper, give a reason and a source for every step, add a gap check for both end positions, and save it with the model.

The macro travels inside the GLB. Any later session can replay it and gets a report per line. This includes your sessions and somebody else’s using only the public demo. See Build with AI.

Wire a customer PLC to a model somebody else built.

List every bindable slot and every signal the running interface offers, match them by their comments, and bind the pairs you are confident about.

This is the case the binding tools exist for, and it is a language problem before it is a technical one: nothing in a tag like MC04_01_Motor_Run says it belongs on the slot Forward of Conveyor_03. Both lists carry the comment stored with each signal — usually the only place a tag’s meaning is written down — and matching those is what a language model is good at.

The tools apply the same type, direction and provider identity validation as a manual drag. They reject an ambiguous target and return the candidates rather than guessing. They confirm a binding by reading it back, not just by requesting it. Repairing a broken link still requires a human click. The viewer’s bindings overview panel shows every link in one table. One click jumps to a link in 3D or removes it. See signal binding for the manual side of the same operation.

Reading the tray line

The MCP server line shows whether the server is running and which clients can reach it:

MCP server: running (/mcp, 8 tools, read/write, no MCP client)

Part	Meaning
`/mcp`	The path, on the gateway port
`8 tools`	What is announced right now — four read tools, four write tools, no browser connected. Open the HMI and the count jumps by the viewer’s tools
`read/write`	The write switch. `read-only` when it is off
`no MCP client`	Connected MCP sessions, with the client’s name when it reports one. This is a different count from the Clients line further down, which means browsers

When the endpoint is switched off entirely, the line says so and names the setting that turned it off.

Switches

Both are in the tray menu, under MCP server:

Switch	Default	Config key	Notes
Enabled	on	`McpEnabled`	Startup switch — the tray offers the restart that applies a change. While off, the endpoint answers 404
Allow write access	on	`McpAllowWrite`	Read live; a change takes effect without restarting, and connected clients are told the tool list changed

Both are persisted in connect-config.json. Write access carries no separate key requirement: MCP writes reach the same signals as the REST write endpoints and are governed by the same access rule.

The write switch protects against an assistant calling something it should not. It is not a security boundary. The checks below decide who may reach the endpoint.

Who may reach the endpoint

Four independent checks run before a tool call is dispatched:

Origin and Host — the MCP specification’s defence against DNS rebinding. A browser page from an untrusted origin is refused. Unlike the HMI backchannel, same-origin is not accepted here: no page CONNECT serves ever calls /mcp.
API key — the general access rule: a loopback peer, or a valid key in the X-API-Key header (or the equivalent Authorization: Bearer spelling). No key in the query string.
Loopback client gate — MCP clients are restricted to the local machine by default, and the restriction is fail-closed: a client whose address cannot be determined counts as remote. Lift it with McpClientRemoteAllowed, and only together with an API key.
Write gate — McpAllowWrite, as described above.

This restriction does not apply to a remotely opened HMI. That is a browser session, protected by the session cookie and the origin check described under remote access.

Setting up a client

Point the MCP client at the endpoint. For an assistant that reads .mcp.json:

{
  "mcpServers": {
    "realvirtual-CONNECT": {
      "type": "http",
      "url": "http://localhost:5100/mcp"
    }
  }
}

Remote clients add the API key as a header, exactly like any other caller.

An assistant that can only launch local programs - Claude Desktop in its classic form - cannot speak to an HTTP endpoint directly and needs a small relay in between. The AI assistant (bridge) page has that configuration, together with the browser side: the browser tools only appear once AI control is switched on in the viewer.

If the client reports no tools, check the tray line first: it distinguishes a switched-off endpoint from a running one that simply has no browser attached yet.

Using the hosted viewer with a local gateway

The browser tools do not require the viewer to be served by the gateway. The hosted viewer on https://web.realvirtual.io can attach to CONNECT running on the same PC. This works for the public demo or a library document you opened there. The assistant then sees that scene.

Two things make it work:

You pair the hosted origin once. realvirtual’s own origins are always allowed to call the gateway, but the AI Bridge is a stronger grant: the first time the hosted viewer attaches, the tray asks whether to pair https://web.realvirtual.io. Allow is remembered; the tray can revoke it later (see browser-origin checks).
The viewer is told where the gateway is. A page that is not served by CONNECT cannot guess it, so add the port to the address once:

https://web.realvirtual.io/demo?mcpPort=5100

Then open Settings ▸ AI in the viewer and switch AI control on. The panel’s Port row shows 5100, the tray line’s tool count jumps, and the client’s tool list gains the web_* family. The setting is remembered per browser profile, so the parameter is only needed the first time.

A gateway started on another port with REALVIRTUAL_CONNECT_PORT is addressed the same way, with that port. A viewer served from your own domain works identically once its origin is added to AllowedOrigins.