Skip to main content

OPC UA Modeler for AI assistants (MCP)

The OPC UA Modeler exposes its type catalog and model tooling over the Model Context Protocol (MCP), so an AI assistant can look up companion specification types, resolve namespace dependencies, find engineering units and validate a model — instead of guessing at them.

There are two ways to connect, and they expose the same twelve tools.

Option 1 — remote connector (no install)​

Add this URL as a custom connector in an MCP client that supports remote servers (Claude.ai: Settings → Connectors → Add custom connector):

https://api.opcua-modeler.sterfive.io/mcp

Nothing to install. The catalog tools work immediately, with no authentication. The three tools that run the modelling engine need your API key: add it to the connector as an API token, see Adding your key to a remote connector.

Option 2 — local, over stdio​

Runs on your machine, and can be pointed at an on-premise backend so model content never leaves your network.

{
"mcpServers": {
"opcua-modeler": {
"command": "npx",
"args": ["-y", "node-opcua-modeler-mcp-server"],
"env": {
"OPCUA_MODELER_API_KEY": "stfv_your_key_here"
}
}
}
}

OPCUA_MODELER_API_KEY is optional — omit it and you still get every catalog tool plus opcua_model_validate.

VS Code (GitHub Copilot)​

VS Code reads .vscode/mcp.json (or the user configuration opened with MCP: Open User Configuration), and its top-level key is servers, not mcpServers. A file copied from the example above is silently ignored.

{
"inputs": [
{ "type": "promptString", "id": "opcua-modeler-api-key", "description": "OPC UA Modeler API key (optional)", "password": true }
],
"servers": {
"opcua-modeler": {
"type": "stdio",
"command": "npx",
"args": ["-y", "node-opcua-modeler-mcp-server"],
"env": { "OPCUA_MODELER_API_KEY": "${input:opcua-modeler-api-key}" }
}
}
}

Save the file and click Start above the server entry. In Copilot Chat, switch to Agent mode (Ask and Edit modes never call MCP tools) and check that the tools are ticked under the tools icon. MCP: List Servers → Show Output shows why a server failed to start. Business and Enterprise seats also need the organisation's MCP servers in Copilot policy turned on.

VS Code connected to WSL. A server defined in the workspace's .vscode/mcp.json (or in MCP: Open Remote User Configuration) runs inside WSL, so it needs Node.js installed in WSL, not on Windows. VS Code does not start it from an interactive shell, so a Node installed with nvm is not on its PATH: give the absolute path printed by which npx as command, or use "command": "bash", "args": ["-lc", "npx -y node-opcua-modeler-mcp-server"].

Pointing at an on-premise backend​

With a licensed CLI running opcua-modeler serve:

"env": { "OPCUA_MODELER_BACKEND": "local" }

The two backends are never mixed and there is no fallback between them: if the local server is down the call fails rather than quietly going to the cloud, because silently sending a model off-network would be a data-egress bug rather than a convenience.

serve and the MCP server must run as the same user on the same system. They talk over a named pipe (Windows) or a Unix socket (Linux, macOS), which cannot cross from Windows into WSL. Under WSL, start serve in a WSL terminal, not in PowerShell.

serve advertises its socket and token in a discovery file that only its user can read:

SystemDiscovery file
Windows%LOCALAPPDATA%\opcua-modeler\serve.json
Linux, macOS, WSL$XDG_RUNTIME_DIR/opcua-modeler/serve.json, and a copy in /tmp/opcua-modeler-<user>/serve.json

The copy exists because an editor does not always pass XDG_RUNTIME_DIR to the MCP servers it starts: under WSL, the terminal running serve has it while the VS Code server may not. The MCP server looks in both places. serve prints both paths at startup. With a CLI or MCP server that predates this, set XDG_RUNTIME_DIR in the MCP server's env to the value echo $XDG_RUNTIME_DIR prints in the terminal running serve.

Example prompts​

Ask in plain language — the assistant picks the tools.

1. Discover the right base type before modelling

I need to model a weighing scale for a packaging line. Which OPC UA companion specification should I build on, what type should my device subtype, and what mandatory members will I have to provide?

Exercises list_namespaces, search_types, get_type_details.

2. Get the namespace block right

I'm writing a model that uses MachineTool and Robotics types. What exactly needs to go in the namespaces: section of my YAML, in the right order?

Exercises resolve_dependencies — the full transitive chain, which is easy to get wrong by hand and fails at generation time when you do.

3. Avoid reinventing a standard block

My device needs a serial number, manufacturer and software revision. Is there a standard OPC UA interface or AddIn that already provides those, rather than me declaring them inline?

Exercises find_reusable_block.

4. Check units, then validate

The sensor reports rotational speed in revolutions per minute and temperature in celsius. Give me the correct UNECE unit symbols, then validate this model:

namespaceUri: http://example.com/sensor/

Exercises find_engineering_unit and opcua_model_validate.

API keys​

Most tools need no key. These three do, because they run the modelling engine:

ToolNeeds a key
resolve_dependencies, list_namespaces, list_types, get_type_details, search_types, find_reusable_block, find_engineering_unitno
get_dsl_reference, opcua_model_validateno
opcua_model_generate, opcua_model_reverse, opcua_model_createyes

To get one: register at opcua-modeler.sterfive.io, then create a key under Settings → API. Where it goes depends on how you connect:

  • Local stdio server: set it as OPCUA_MODELER_API_KEY in the MCP server's configuration (see Option 2 above).
  • Remote connector: add it to the connector as an API token, below.

Adding your key to a remote connector​

The hosted connector reads your key from each request: the client sends it as Authorization: Bearer stfv_..., and the connector passes it on to the OPC UA Modeler API for that call only. It is not stored by the connector. Without a key, the connector stays anonymous: the catalog tools and opcua_model_validate keep working, and the three keyed tools report "Authentication required".

Mistral Le Chat. Add a custom MCP connector with the URL https://api.opcua-modeler.sterfive.io/mcp, choose API token as its authentication method, and paste your stfv_... key. For a connector you already added, edit it and set the token the same way.

Claude.ai and other clients. If the client's connector settings offer a bearer or API token field, paste the key there. A client that only lets you add custom headers can send it as X-Api-Key: stfv_... instead. A client that offers only OAuth, or no authentication setting at all, cannot send a key: use the local stdio configuration for the three keyed tools.

When the key is rejected or expired, the tool's error says to update the API token in your connector settings, not an environment variable.

Rate limits​

CallerLimit
Anonymous (no key)50 calls/day per IP
Free tier key25 calls/day
Paid planssee pricing

If you hit a limit the tool reports how long to wait. Current plan details and quotas live in your account under Settings → API — the tools themselves deliberately do not carry pricing or upgrade messaging.

Troubleshooting​

"Authentication required" — the tool needs a key. On a remote connector, set it as the connector's API token (see Adding your key to a remote connector). Locally, check OPCUA_MODELER_API_KEY is set in the MCP server's config, not just in your shell: MCP clients start the server with their own environment.

"Cannot reach the OPC UA Modeler API" — network or DNS. Check the API health endpoint.

Key expired — beta keys carry a fixed window. Rotate at Settings → API ("Rotate & extend"), then update the value in your config or in the connector's API token.

On-premise: "No on-premise OPC UA Modeler server found" — start opcua-modeler serve, and keep it running: it deletes its discovery file on exit. The error lists every path the MCP server looked in; compare them with the discovery lines serve printed. If they differ, the two run as different users or on different systems (Windows and WSL), see Pointing at an on-premise backend. The token is read from the discovery file, so if the server restarted, retry to pick up the new one.

VS Code: the server runs but Copilot shows no tools — switch Copilot Chat to Agent mode and tick the tools under the tools icon. A .vscode/mcp.json using mcpServers instead of servers is ignored without an error.

Source​

The MCP server is open source and published to npm as node-opcua-modeler-mcp-server — github.com/node-opcua/node-opcua-modeler-mcp-server.