Skip to main content
Firmware Stable

AI agent (MCP)

Connect your AI agent to emGUI, and it works with the device on your desk: it reads its values, finds the answers in this documentation, and takes you through setup, tuning and diagnosis the way our support does. It works for every siliXcon device emGUI connects to: motor controllers, battery management systems (BMS) and displays.

What you need

SWTools 4.0.0-rc4 or newer (download), and an AI agent that runs on your PC: Claude Desktop, Claude Code, Cursor, VS Code with GitHub Copilot, the ChatGPT desktop app, Codex or Gemini CLI. Chats in the browser or on the phone (claude.ai, ChatGPT in the browser, the mobile apps) run in the vendor's cloud and cannot reach your PC.

Connect your AI agent​

Start emGUI and connect to your device. Tick AI assistants → Allow AI assistants, or click the AI button in the toolbar and allow them there. Then:

  • Claude Desktop: download the emGUI extension and open it, then click Install. With the Microsoft Store version of Claude Desktop, drag the file into the Claude Desktop window instead.
  • ChatGPT desktop app: under Set it up by hand instead below, open the ChatGPT desktop tab and click Add emGUI to ChatGPT. ChatGPT shows the emGUI plugin, which comes with SWTools: install it.
  • Any other agent: copy the message below and paste it into your AI agent. The agent reads this page and sets itself up. Restart the agent when it asks you to.

Every agent connects the same way: it starts emgui-mcp, a small program SWTools installs next to emGUI, which finds the running emGUI by itself. You need no Node.js, no address and no port.

Paste this into your AI agent

Connect yourself to emGUI, the siliXcon device tool on my PC: follow the "Instructions for AI agents" on this page. https://docs.silixcon.com/docs/sw/swtools/mcp

Set it up by hand instead
Your system

Every agent starts emgui-mcp, which SWTools installs next to emGUI: emgui-mcp (the installer puts it on your PATH).

Download the emGUI extension and open it: Claude Desktop shows its install screen, where you click Install. With the Microsoft Store version of Claude Desktop, which does not open such files, drag it into the Claude Desktop window instead, or pick it under Settings → Extensions → Advanced settings → Install Extension….

Download the emGUI extension

The extension expects SWTools in its default folder. Installed it somewhere else? Add emGUI by hand, as below, with the path of emgui-mcp in your installation.

Or add emGUI to Claude Desktop's configuration file by hand:

  1. In Claude Desktop, open Settings → Developer → Edit Config. This opens claude_desktop_config.json.
  2. Add the emgui entry:
    claude_desktop_config.json
    {
      "mcpServers": {
        "emgui": {
          "command": "emgui-mcp"
        }
      }
    }

    If the file is empty, paste this as it is. Otherwise add mcpServers inside the file's outer { }, not as a second { } after it. If the file already has mcpServers, put the emgui entry inside it, next to the others.

  3. Save the file. Then quit Claude Desktop completely and start it again.
Two things that do not work

A "url" entry in this file. Claude Desktop does not support it, and it can delete all your MCP servers from the file when it starts.

Customize → Connectors → Add custom connector. It connects from Anthropic's cloud, which cannot reach your PC.

emGUI does not show up? Claude Desktop writes its MCP logs, including what emgui-mcp reports, under Settings → Developer (Windows: %APPDATA%\Claude\logs, macOS: ~/Library/Logs/Claude).

You stay in control​

  • At first the agent can only read: list the devices, read their values and run commands that change nothing.
  • To let it change parameters, choose AI assistants → Allow writes in emGUI. Commands that move a motor, such as the motor identification, or that change how the device is reached need AI assistants → Allow dangerous commands: emGUI explains what that allows and asks you to confirm. Choose it only with the hardware in sight. The agent cannot raise the level itself, and it asks you before every step that changes the device.
  • Precaution: dangerous commands run through a tool of their own, Run a dangerous device command (execute_dangerous_command). When your agent asks permission to use it, allow it once, never always allow: then you confirm every such command in your agent before it runs.
  • The AI button in emGUI's toolbar always shows where you are: OFF, READ, WRITE or DANGEROUS. While it is off, click it to allow AI agents (tick Remember to keep them allowed for the next start too); once they are allowed, it opens this page. Switch them off under AI assistants → Allow AI assistants.
  • emGUI starts with AI agents not allowed and read only. AI assistants → Remember settings keeps your choice for the next start. While writes are allowed, the emGUI window title says so.
  • emGUI sends nothing to the internet except documentation lookups. Your agent is a separate program: if its AI model runs in the cloud, it sends your conversation, including the values it read from the device, to its provider. It never sees a password or the service token.

What to ask​

  • "Set up my controller for its motor."
  • "Help me tune my controller: what limits the power and the speed now, and what should I change?"
  • "Why does my device not run?"
  • "Which devices are connected, and which firmware do they run?"

Behind the answers are siliXcon's playbooks: step-by-step procedures for setup and diagnosis, written by our engineers per device family and application. emGUI downloads the current ones when your agent asks for them, so it follows the same order of checks as our support.

What the agent can use, and the levels in detail
  • Device tools: list the connected devices, read and write their values, and run commands, within the level you set.
  • execute_dangerous_command (Run a dangerous device command): the commands that can move a motor or change how a device is reached have a tool of their own. Let your agent ask you before every use of it: allow it once, never permanently.
  • emgui_status: the emGUI version, the level, and which interface emGUI uses and whether it is connected. The agent cannot change the interface.
  • list_emgui_instances and select_emgui_instance: when more than one emGUI runs, the emGUIs and their devices, and the one the agent works with. It switches only when you ask.
  • list_playbooks and get_playbook: siliXcon's playbooks, and those of your private documentation site if you have one. The ones that match the connected device are marked.
  • search_docs, search_private_docs, read_doc and doc_link: search and read this documentation and your private documentation site, and find the page of one variable of the connected device.
  • decode_hwid: what a device's hardware variant has, from its hardware ID. The voltage in a hardware ID is a component rating, not the battery or supply voltage you may connect: the agent is told to read the maximum working voltage on the device's specification page.
Level (emGUI AI assistants menu)The agent may also
Read only (the default)Nothing more.
Allow writesChange parameters and run commands that change the device state.
Allow dangerous commandsRun commands that change how the device is reached (its address or interface) or act on the hardware it drives, such as moving a motor. Hardware in sight.

The level applies at once. emGUI can also start with it: --mcp-write=write or --mcp-write=danger.

Private documentation​

If siliXcon made a firmware application for you, its documentation is on a private site of your own, such as https://<name>.private.silixcon.com, behind a user name and password. Set it up in emGUI once, and your agent searches and reads it next to this public documentation:

  1. In emGUI, click Help → Documentation site....
  2. Enter the address, the user name and the password your siliXcon contact gave you.
  3. Click Test, then OK.

Leave Remember password in the system keychain ticked, and emGUI keeps the password in the system keychain (Windows Credential Manager, the macOS Keychain, or a Secret Service keychain or KDE Wallet on Linux), never in a file. Without a keychain, you enter it again after each start of emGUI. If your emGUI has no Documentation site... in its Help menu, update SWTools. The dialog is described on the emGUI page; for a single run, see its CLI options.

Never type the password into the chat

emGUI logs in to your private site itself; the agent never needs the password. If an agent asks for it, enter it in emGUI under Help → Documentation site... instead. Anything you type into a chat goes to the agent's provider.

Troubleshooting the connection​

The agent could not open this page. Some agents cannot read web pages. Open Set it up by hand instead above and follow the steps for your agent.

The agent does not see emGUI's tools.

  • emGUI must be running, with AI assistants → Allow AI assistants ticked. Until it is, the agent sees only emgui_status, which tells it what is missing: whether emGUI is not running at all, or runs with AI agents not allowed. As soon as emGUI is there, the tools appear by themselves; if they do not, reconnect the server from the agent's list of MCP servers (Claude Code: /mcp) or restart the agent (quit Claude Desktop completely).
  • emGUI and the agent must run on the same computer, as the same user.

The agent cannot start emgui-mcp ("command not found", ENOENT, "spawn emgui-mcp").

  • Your SWTools is older than 4.0.0-rc4, which brought emgui-mcp. Update it.
  • Windows: the installer puts SWTools on your PATH, but an agent that was already running does not see it. Restart the agent; if that is not enough, sign out of Windows and in again. Or give the full path instead: C:\Program Files\silixcon\swtools\bin\emgui-mcp.exe (in a JSON file, write each \ twice).
  • macOS and Linux: the command is the full path, /Applications/swtools.app/Contents/MacOS/emgui-mcp or /opt/swtools/bin/emgui-mcp. If you unpacked SWTools for Linux elsewhere, use that folder.

Two emGUIs are running. The agent asks you which one to use, and describes each by its devices and interface. Once it is connected, it stays with that emGUI, also when you close it and start it again; it never moves to the other one by itself. To switch, ask the agent to use the other emGUI. Each emGUI shows its port in its Log panel, for example MCP server: pipe emgui-mcp-28956 for emgui-mcp. To fix the choice in the configuration instead, add --port=28956: in a JSON file as "args": ["--port=28956"] next to "command", on a command line after emgui-mcp.

See what the agent asks. Tick AI assistants → Log MCP requests (or start emGUI with --mcp-log). Every request then appears in the Log panel. If nothing appears when you ask your agent something, it does not reach emGUI.

The agent says emGUI is not connected to the device. In emGUI, click Connection → Connect; without an interface, first Connection → Load interface.... See Communication interfaces.

Playbooks or documentation are "unavailable". They come from docs.silixcon.com, and from your private documentation site if you have one. Without internet access the agent says so and continues with what the device reports.

Your private site: no site set up, password missing, or login refused. Check the address, user name and password under Help → Documentation site... and click Test. A site last updated before emGUI's AI support has no AI search yet; it comes with the site's next update.

An agent that only takes a URL

emGUI also serves MCP over HTTP, at http://127.0.0.1:28955/mcp. The emGUI Log panel shows the exact one when the server starts, since a second emGUI uses the next free port. Every agent on this page can start emgui-mcp, which is the better way: it needs no port, and no antivirus web filter can get between the agent and emGUI. emGUI refuses requests from websites on purpose, so that no website can control your device: a browser cannot connect.

Documentation search without emGUI​

Only want answers from the documentation, without emGUI? Connect the public documentation search directly. It needs no account and no key, and because it is on the internet, AI agents in the browser can use it too:

https://docs.silixcon.com/mcp
  • claude.ai and Claude Desktop: Customize → Connectors → Add custom connector, then paste the URL.
  • ChatGPT in the browser (paid plans): turn on developer mode (Settings → Security and login → Developer mode) and add the URL as a developer-mode app. See OpenAI's guide.
  • Claude Code: claude mcp add --transport http --scope user silixcon-docs https://docs.silixcon.com/mcp
  • Codex and the ChatGPT desktop app: codex mcp add silixcon-docs --url https://docs.silixcon.com/mcp, or in the app Settings → MCP servers → Add server with the type Streamable HTTP.
  • Gemini CLI: gemini mcp add --transport http --scope user silixcon-docs https://docs.silixcon.com/mcp
  • Cursor: in ~/.cursor/mcp.json, inside mcpServers, add "silixcon-docs": { "url": "https://docs.silixcon.com/mcp" }.
  • VS Code: in the user mcp.json, inside servers, add "silixcon-docs": { "type": "http", "url": "https://docs.silixcon.com/mcp" }.
It is a search tool, not an oracle

The agent receives matching sections, not the whole documentation, and it can still summarize incorrectly. For anything safety related, such as powering, precharge, protections or current limits, read the linked page before you act on the answer.

Instructions for AI agents​

For your AI agent - you do not have to read this. It follows these steps when you paste the message from Connect your AI agent.

The user asked you to connect yourself to emGUI, the siliXcon tool on their PC. emGUI has a built-in MCP server, which a client reaches through emgui-mcp, a local stdio MCP server installed with SWTools 4.0.0-rc4 or newer. It takes no arguments, needs no authentication, and finds the running emGUI by itself.

  1. The command. Name the server emgui. Its command, by the system the user's PC runs:
    • Windows: emgui-mcp. The SWTools installer puts it on the PATH. Where you can run commands, check that emgui-mcp --version prints a version. If it is not found, use C:\Program Files\silixcon\swtools\bin\emgui-mcp.exe; if that does not exist either, tell the user to install or update SWTools.
    • macOS: /Applications/swtools.app/Contents/MacOS/emgui-mcp
    • Linux: /opt/swtools/bin/emgui-mcp, or bin/emgui-mcp in the folder the user unpacked SWTools to.
  2. Add it to your client as a stdio server with that command and no arguments, keeping every server the client already has: merge into existing files, never replace them. Where you can run commands or edit files, tell the user what you will change and do it. Where you cannot, give the user the exact command or entry and where it goes. <CMD> below is the command from step 1; in a JSON or TOML string, write each backslash of a Windows path twice.
    • Claude Code: claude mcp add --scope user emgui -- <CMD>
    • Codex (CLI and IDE extension): codex mcp add emgui -- <CMD>
    • ChatGPT desktop app: the emGUI plugin comes with SWTools. Tell the user to click Add emGUI to ChatGPT on this page (under Set it up by hand instead, tab ChatGPT desktop) and to install the plugin ChatGPT shows. If SWTools is not in its default folder, or the button does nothing, the user adds the server in Settings → MCP servers → Add server: name emgui, type STDIO, the command. It shares this list with Codex, so the Codex command works as well.
    • Gemini CLI: gemini mcp add --scope user emgui <CMD>. Do not add --trust.
    • Cursor: in ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json), inside mcpServers, add "emgui": { "type": "stdio", "command": "<CMD>" }.
    • VS Code (GitHub Copilot in agent mode): in the user mcp.json (command MCP: Open User Configuration), inside servers (not mcpServers), add "emgui": { "type": "stdio", "command": "<CMD>" }. VS Code asks the user to trust the server when it first starts it.
    • Claude Desktop: tell the user to download the emGUI extension, https://docs.silixcon.com/files/emgui.mcpb, open it and click Install (with the Microsoft Store version of Claude Desktop: drag the file into its window). The extension assumes SWTools in its default folder. Do not edit the configuration file yourself for Claude Desktop: the Microsoft Store version keeps it in a folder of its own and writes it back while it runs. If SWTools is elsewhere, or the user prefers a manual entry, they open Settings → Developer → Edit Config and add, inside mcpServers, "emgui": { "command": "<CMD>" }. Never add a "url" entry to this file: Claude Desktop does not support it and can drop every server it has. Customize → Connectors does not work either: it connects from Anthropic's cloud, which cannot reach the user's PC.
    • A client in a browser or on a phone cannot reach emGUI, which runs on the user's PC only. Tell the user to use one of the clients above.
  3. Restart. Ask the user to restart the client (Claude Desktop: quit it completely) so it starts the server, and to have emGUI running with AI assistants → Allow AI assistants ticked. The order does not matter: until emGUI is there, the server offers only emgui_status, and the tools appear once it is. A restarted client may start a new conversation: if the user asked for more than the connection, such as guiding them through a setup, tell them to ask for it again after the restart.
  4. Check. After the restart, call emgui_status, then follow the server's own instructions. If it says several emGUIs are running, call list_emgui_instances, ask the user which one to use - describe each by its devices and interface - and call select_emgui_instance with its port; never choose for the user. If it says emGUI is not reachable, or the tools do not appear, go through Troubleshooting the connection with the user.