AI Clients (MCP)

Overview

CONNECT exposes a Model Context Protocol endpoint. An AI assistant that speaks MCP can then read signals, inspect the configuration and — when allowed — operate the running HMI, through one endpoint and one URL:

http://localhost:5100/mcp

The tray menu has a Copy Endpoint URL entry for exactly this.

The server is part of the gateway process. There is no second program to install, no Node.js and no 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 WEB session: scene, components, simulation, layout, editor. They appear when a browser is connected and disappear when it closes, and connected clients are notified about the change.

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

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

A write refused by the switch answers with the message that names the switch, so the assistant can tell the operator what to do rather than retrying. Writes also require a valid license — on an expired one they answer LICENSE_REQUIRED — and a write that reaches a PLC is still governed per interface by AllowWebToPlc, which this endpoint neither reads nor overrides.

Browser tools

Everything the viewer can do is announced while a browser is connected — well over a hundred tools, grouped by domain: web_node_* and web_component_* for the scene graph, web_camera_*, web_view_* and web_screenshot* for looking at it, web_drive_*, web_signal_* and web_sim_* for running it, and web_editor_*, web_layout_*, web_des_* and web_plc_* for building. The viewer announces them, so a viewer of a different version announces a different set — the client’s tool list is always the truth about the session in front of it.

web_help(topic) returns the guide for a workflow — editor, layout, simulation, plc, des.

Reading the tray line

The MCP server line answers “is it up, and what can reach it?” in one sentence:

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 — who may reach the endpoint at all is decided by the checks below.

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.

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.