MCP Usage Guide

This page covers the prompt patterns that earn their keep in day-to-day use once the MCP Server connection is in place, and how the tools behave.

The golden rule: name the space and the project

Give the space and project name in every request. Without them the model first makes listing calls to find them — the answer is the same, but it takes a detour to get there.

✗  What is the value of temp_value?
✓  In space guide, project Docs Demo — what is the value of temp_value?

Guide tools

The server offers a separate guide tool per topic. These are called before any write: method signatures, enum spellings and script engine rules change between releases, so the guide — not the model’s memory — is the authority.

Tool	Topic
inscada_guide_script	Writing scripts, the ins.* API
inscada_guide_animation	Animations, element types, expressions
inscada_guide_faceplate	Faceplates and placeholders
inscada_guide_custom_html	Custom HTML pages
inscada_guide_custom_menu	Custom menus
inscada_guide_chart	Charts
inscada_guide_alarm	Alarm definitions and groups
inscada_guide_variable	Variables, scaling, logging
inscada_guide_connection · inscada_guide_protocol	Connections and protocol settings
inscada_guide_trend	Trend definitions
inscada_guide_report · inscada_guide_html_report	Reports
inscada_guide_component	Component library
inscada_guide_role_menu · inscada_guide_access_group	Roles, menus and access rights
inscada_guide_admin_monitor	Administration and monitoring tools

If you do not know where to start, inscada_welcome returns the capability list along with example prompts.

You do not have to ask for the guide

The model calls the guide for whatever topic it is about to write to. Even so, opening an animation or script job with “read the guide first” is the shortest way to stop it working from memory.

Scenarios

The examples below are written against the Docs Demo project in the guide space.

Reading live values

No guide needed.

In space guide, project Docs Demo — value of temp_value?

In space guide, project Docs Demo — show the current values of all variables

In space guide — check the connection statuses

Historical data and charts

No guide needed; state the time range.

In space guide, project Docs Demo — chart temp_value for the last 24 hours

In space guide, project Docs Demo — compare temp_value and press_value, last 6 hours

In space guide, project Docs Demo — 7-day statistics for temp_value

Finding variables

In space guide, project Docs Demo — list the variables

In space guide, project Docs Demo — list variables whose name contains "press"

Alarms and status

In space guide — show the active alarms

In space guide, project Docs Demo — project status

Writing scripts

The guide is required. The script engine is ES5 and the ins.* signatures move with the release.

Read the script guide first. In space guide, project Docs Demo —
write a script that runs every 10 seconds and raises a notification
when temp_value goes above 60

The same order holds for changing an existing script:

Read the script guide first. In space guide, project Docs Demo —
read the "Pump Supervisor" script and change its threshold to 65

Searching inside scripts needs no guide:

In space guide — search the scripts for "getVariableValue"

Creating animations

The guide is required. Element types and expression types are what go wrong.

Read the animation guide first. In space guide, project Docs Demo —
create an SVG animation showing temp_value, press_value and tank_bar

On Bar and Pipe elements the visual settings can also be decided at run time: when an EXPRESSION returns an object, the fields on that object are used instead of the stored props — which is what lets one expression drive both the flow state and its colour.

Read the animation guide first. In space guide, project Docs Demo —
create a water system mimic. The pipe should change colour and speed
with pump state: blue and flowing when running, grey and stopped when off

For that request the expression comes out closer to this than to return true/false:

var running = ins.getVariableValue('motor_lamp') == 1;
return {
  value: running,
  fillColor: running ? '#04B3FF' : '#999999',
  speed: 2000,
  strokeArray: 10
};

Returning an object overrides props only on Bar and Pipe

On the other types, an object returned by the expression is unwrapped for its value field alone; colour, speed and width are read from the element’s stored props. Detail: Element Editor.

Dashboards

Working from a template needs no guide; custom HTML does.

In space guide, project Docs Demo — gauge dashboard for temp_value, 0-100

Read the custom HTML guide first. In space guide, project Docs Demo —
custom HTML dashboard: three gauges on top, a trend chart below

Bringing external resources in-house. Custom HTML pages are subject to the content security policy. Rather than pulling JS, CSS, fonts or images from a CDN that is not allowed, upload the file to the platform and serve it locally. An uploaded file is served from /api/files/static/<name>; pointing the page at that path instead of the CDN is all it takes.

In space guide — upload chart.min.js to the static files,
then build the dashboard referencing it instead of the CDN

Exporting to Excel

In space guide, project Docs Demo — export 24 hours of temp_value to Excel

Exploring the API

Find the alarm endpoints in the inSCADA API

Quick reference

Task	Prompt pattern	Guide
Live value	In space X, project Y — value of <var>?	No
Chart	... chart <var> for the last 24 hours	No
Gauge	... gauge dashboard for <var>, 0-100	No
Statistics	... 7-day statistics for <var>	No
Alarms	In space X — show the active alarms	No
Project status	In space X, project Y — project status	No
Variable list	... list the variables	No
Script	Read the script guide first. ...	Yes
Animation	Read the animation guide first. ...	Yes
Custom dashboard	Read the custom HTML guide first. ...	Yes
Excel	... export 24 hours of <var> to Excel	No
API discovery	Find the <topic> endpoints in the inSCADA API	No

Compact and verbose responses

By default the tools return only the fields that are needed. When you want the raw fields, saying “give me the detail” or passing verbose: true is enough.

inscada_get_live_value — default:

{
  "value": 421.79,
  "name": "temp_value",
  "dsc": "Bearing temperature",
  "date": "2026-04-03T00:43:08"
}

The verbose response adds the scaled/raw distinction (flags, extras.raw_value), the variable’s frame–device–connection chain, and the epoch-millisecond stamp.

list_variables — returns id, name, type, unit and dsc by default; verbose also brings connection_id, project_id, the scaling limits and the logging settings.

What drives token use

• Naming the space and project is the single biggest saving; the model makes no discovery calls.
• The guide loads only when it is needed. Do not ask for it when you are reading a live value.
• Leave the compact default alone. “Detail” pays off when you genuinely need a raw field.
• Ask for variables filtered. On a project with 500 variables, filtering by name instead of “list the variables” shrinks the response noticeably.
• A small model is enough for simple queries; the script and animation work that needs a guide is better on a large one.