AI agents over MCP
NEXT HMI speaks MCP (Model Context Protocol), so an AI assistant can read and edit a project the same way you would in the editor — add pages, place widgets, wire bindings, add alarms, fill in translations. It is off for writes by default, and you decide per project.
The assistant talks to your installation directly: your project files never pass through a NEXT HMI service, and there is nothing to sign up for. What the endpoint hands out is exactly what the client asks for, over your own network.
How it fits together
One endpoint covers the whole installation:
| Setup | Endpoint |
|---|---|
| HTTP (default) | http://<manager-host>:8000/mcp/ |
| HTTPS turned on | https://<manager-host>:8443/mcp/ |
Either spelling works. /mcp/ is the canonical path; a bare /mcp is rewritten onto it rather than redirected, because most MCP clients do not follow redirects.
Client and manager on the same machine? Then <manager-host> is 127.0.0.1 and http://127.0.0.1:8000/mcp/ is the whole endpoint. From another machine, use the manager's name or address — the manager binds every interface unless NEXTHMI_HOST says otherwise, and every request to /mcp has to carry a token either way. The hmi.local examples further down are for that case.
With HTTPS on, port 8000 answers with a 307 redirect rather than the app — and most MCP clients do not follow redirects. Point the client at the HTTPS port directly. See Ports. If the certificate is the self-signed one the manager generated, the client must be told to trust it; a client that validates certificates will otherwise refuse to connect.
It is served by the manager, the only process that sees every project, so an agent connects once and never reconfigures as projects start, stop or get created. Every tool call names which project it acts on, so one session can work across several.
A project does not need to be running to be edited — the tools work on the files. If the project is running, each write is pushed to the live instance, which re-reads the affected files and tells every connected browser.
Turn it on
1. Enable writes for the project
On the Manager dashboard, tick MCP write enabled on the project's row. Off is the default. With it off, an agent can still read that project; every write is refused.

2. Find the project id
Every tool call names a project by id, not by its display name. The id is the slug in the project's own URLs — open the project and read /runtime/<id>/ or /editor/<id>/ from the address bar. It is also the project.id field in the project's config.json, and an agent with any token can call projects_list to see them all.
3. Create a token
A headless client (an agent runner, a desktop assistant) has no manager session, so it authenticates with a bearer token. One token covers every project on this installation, so you create it once. On the Manager dashboard, open Settings and click Create token in the Tokens section. Keep the kind on MCP. The dialog asks for:
- Token name — any label, so you can tell tokens apart later (AI agent on my laptop, CI runner).
- Read or Write — the access level the token has on every project. A write token still needs MCP write enabled ticked (step 1) on each project it writes to.
Click Create token. The dialog then shows, each with a Copy button:
- the token itself,
- the server URL, and
- the
mcpServersJSON for agents configured by file,
with this installation's endpoint already filled in — the address the dashboard is open on, so with HTTPS on it is the 8443 one. The token is shown once: only its hash is stored, so a lost token cannot be recovered, only replaced. Only Done closes the dialog while the token is on screen.

From a script. POST /api/manager/mcp/pair mints the same token without a dashboard session, taking the device-admin password in the body instead — the one that unlocks the dashboard (see Managing projects), not a project's operator password:
curl -X POST http://localhost:8000/api/manager/mcp/pair \
-H 'Content-Type: application/json' \
-d '{"password":"<device-admin>","access":"write","name":"Agent runner"}'
From Windows PowerShell, use Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '<the same JSON>' and pass the JSON inline: a body file written with Out-File or Set-Content starts with a byte-order mark, and the server rejects it with a JSON parse error at line 1 column 1.
4. Point the client at it
The dialog in step 3 already shows these filled in; they are spelled out here for a token minted from a script.
Any AI agent that speaks MCP over Streamable HTTP can connect. It needs the server URL, https://hmi.local:8443/mcp/, and the header Authorization: Bearer <token>. Agents configured by file mostly take this shape:
{
"mcpServers": {
"nexthmi": {
"type": "http",
"url": "https://hmi.local:8443/mcp/",
"headers": { "Authorization": "Bearer <token>" }
}
}
}
Some agents name the fields differently (servers for mcpServers, serverUrl or httpUrl for url); the URL and the header stay the same. A command-line agent may take them as flags instead — Claude Code, for example:
claude mcp add --transport http nexthmi https://hmi.local:8443/mcp/ \
--header "Authorization: Bearer <token>"
hmi.local is an mDNS name and only resolves on a client that speaks mDNS — Linux needs avahi, Windows has no resolver of its own and needs Bonjour installed. If the name doesn't resolve, that is a plain DNS failure and not a certificate problem: use the machine's IP address, or add a hosts entry for it.
Working in a browser that is already signed in to the manager? Then the manager session is enough and no token is needed — you already have that privilege through the dashboard.
5. Try it
Ask for a read first, so a bad endpoint or a mis-scoped token shows up before anything is written:
- "List the pages in project line-a." — exercises the connection, the token and the project id in one call.
- "What variables does the LinePLC datasource have?" — confirms the agent can see your data model.
- "Add a page called Line overview with a heading and a button bound to LinePLC:Motor/Start." — the first write. Watch the editor tab: the change lands on disk and an open editor shows it, or offers to reload when it has unsaved changes.
Managing tokens
| Action | How |
|---|---|
| List issued tokens | Settings › Tokens on the Manager dashboard lists every token: name, kind, access level (or, for an API token, its scopes) and creation time, never the secret. GET /api/manager/mcp-tokens returns all of them, with ids. |
| Revoke one | Revoke on its row in that list, or DELETE /api/manager/mcp-tokens/<id>. |
| Revoke everything | Change the device-admin password. |
Because the secret is shown once, the way to check a token is still live is to look for it in that list: a missing token means revoked, and a present one means the fault is in the client's URL, header or scope. Confirm the rest with one initialize call against /mcp/ before assuming the client is misconfigured.
Tokens do not expire on their own. One stays valid until it is revoked by id, or until the device-admin password changes — so treat a token handed to a laptop or a CI runner as live until you take it back.
What an agent can do
| Area | Agent may |
|---|---|
| Pages, widget trees, widget properties | read + write |
| Global events, variable triggers included | read + write |
| Variables on a datasource | read + write |
| Alarms (definitions) | read + write — groups are UI-only |
| Translations (languages, keys, cells) | read + write |
| Assets (icons, images) | read + write |
| Datasource connections and browsed trees | read only — passwords (a password written into the server URL included) and the private-key path read as <redacted> |
| Components | read only |
| Users — names, groups, enabled state | read only, never credentials |
| Widget-schema manifest | read only |
| Starting, stopping, creating, deleting projects | never — lifecycle stays an operator action in the dashboard, on purpose |
Destructive operations are two-step — the first call returns a diff to review, and only a second call with confirm: true applies it. Page edits also return a warnings list for advisory problems such as an incomplete binding or a reference to a variable that doesn't exist; the write still succeeds, so it's worth reading them.
An uploaded icon must be an .svg; an image a .png, .jpg/.jpeg, .webp, .gif or .svg, and a picture file must really be one. Every SVG is rebuilt from a safe subset of shapes, gradients and text: scripts, event handlers, embedded HTML, <style> blocks and links to other files are dropped, and the agent gets a warning for each removal. An icon drawn with a <style> block of CSS classes therefore comes out unstyled; ask the agent to use fill and stroke attributes instead.
The full tool catalog, argument shapes and limits are in the MCP reference.
Starter prompts
The server ships four prompts — canned multi-step recipes that appear in your client's prompt or slash menu once connected, so you don't have to describe the whole workflow yourself. Each one takes the project id plus a couple of arguments:
| Prompt | Does | Arguments |
|---|---|---|
| Scaffold a new page | Creates a page and a starter widget tree from a one-line brief. | project, brief, layout (default single-column) |
| Build a datasource dashboard | Reads a datasource's variable tree and builds a page that visualises the important ones. | project, datasource, max_widgets (default 12) |
| Seed alarms from a datasource | Walks the boolean variables, picks the ones that name a fault, and writes alarm definitions into an existing group. | project, datasource, group_title (default Auto-seeded) |
| Localize a page's strings | Extracts the static strings on a page into a dictionary and rewrites the page to use $loc bindings. |
project, page_id, dict_name (default Default) |
They are ordinary instructions, not privileged calls — the agent still works through the same tools and the same gates.
While an agent is working
Operator screens show it after a reload. A running project re-reads the changed files at once, but an open live view keeps what it shows until its browser tab is reloaded, so nothing on an operator's screen changes under their hands. Alarms the agent adds go off straight away.
Editor tabs follow along, or ask first. An editor with nothing unsaved shows the agent's change straight away, without a reload. One with unsaved changes shows a banner instead — "Config was updated by another writer." — with the choice to reload or dismiss, rather than yanking the canvas out from under you mid-edit. Dismissing keeps your tab as it is. Saving then writes only the pages you changed, so the agent's edits to other pages stay. If you and the agent changed the same page, the page list or the translations, the save is refused instead of overwriting the agent: reload, then make your change again.
When it doesn't work
| What you see | What it means |
|---|---|
401 · MCP requires a manager session or a valid MCP bearer token |
No Authorization header reached the server, or the token was revoked — including by a device-admin password change, which revokes every token. |
| MCP token has read-only access | Created as Read. Access level is fixed when the token is made; create a Write one. |
| MCP writes are disabled for project '…' | The token is fine, the project's MCP write enabled tick is not. Step 1 above. |
401 with a token made in version 1.0 or 1.1 |
Those tokens named one project. Tokens now cover every project, so an old one is refused rather than widened. Create a new one under Settings › Tokens. |
422 Extra inputs are not permitted on projectId while pairing |
Pairing no longer takes a project: a token covers every project. Drop projectId from the body. |
429 · Too many failed attempts from <address>. Try again in Ns. |
Five wrong device-admin passwords from this machine's address, on /pair or wherever else the password is asked; the same lockout that guards the dashboard login. Wait it out; other machines are not affected. |
404 · Session not found after a pause |
A session idle for 30 minutes is closed. Most clients open a new one on their own; otherwise reconnect the client. |
503 · Too many open sessions |
1 000 sessions are open at once, usually a client that starts a new one for every call and never ends it. Idle ones close after 30 minutes; restart that client, or wait. |
404 on GET, 405 on POST, or a bare 307 |
The URL reached the router but not the transport — add the trailing slash (/mcp/). A proxy in front can rewrite the path too. |
Connection refused on 8443 |
HTTPS was never turned on, so nothing listens there. Use the 8000 HTTP endpoint, or enable HTTPS first. |
| Host name doesn't resolve at all | hmi.local needs mDNS on the client — Bonjour on Windows, avahi on Linux. Use the IP address or a hosts entry instead. |
| Client cannot connect at all, no HTTP status | Usually the redirect or the certificate: HTTPS moves the app to 8443, and a generated self-signed certificate isn't trusted by default. See the endpoint table above. |
| Agent claims a widget type doesn't exist | The widget-schema manifest can lag by one save cycle after a custom widget is edited. Re-save the widget and let the agent re-read the schemas. |
Before you enable it
An agent with a write-scoped token can change what operators see and what values get written to a PLC. Treat the endpoint as equivalent to editor access.
- Keep it on a trusted network. The endpoint is plain HTTP unless you've turned on HTTPS. A bearer token crossing an untrusted network is a bearer token someone else can use. See What is reachable without a password for what the rest of the device leaves open.
- Grant the narrowest scope that works. A
readtoken for an agent that only answers questions about the project;writeonly where you want edits. - Confirmation guards the agent, not you. An agent can chain the dry-run and the confirm in a single turn without asking a human. The MCP toggle is the control that actually stops writes.
- Attribution is best-effort. Writes are labelled with the client's name, but any authenticated caller can set that label, so treat the log as advisory rather than proof.