Skip to main content
Firmware Stable

AI assistant (MCP)

note

This require SWTools v4.0.0-rc3 and newer.

What it is​

emGUI has a built-in MCP server. MCP (Model Context Protocol) is the standard way for AI assistants such as Claude, ChatGPT, Cursor or GitHub Copilot to use outside tools. Once you connect your assistant, it can see the devices emGUI is connected to, read their values, search this documentation and follow siliXcon's diagnostic playbooks. All of it goes through one address on your own PC.

emGUI itself sends nothing to the internet except documentation lookups on docs.silixcon.com. Your assistant is a separate program: a cloud assistant sends your conversation, including the values it read from the device, to its provider.

Requirements​

  • SWTools 4.0 with emGUI, running and connected to your device. Download SWTools.
  • An AI assistant app installed on your PC: a desktop app, a code editor or a command-line tool. The AI behind it may run in the cloud; the app has to run on your PC to reach emGUI. The tabs below list the ones we have checked.
  • The server URL. In emGUI, click MCP → Copy server URL. It is usually http://127.0.0.1:28955/mcp. A second emGUI running at the same time uses a different port, so always copy it.
  • Internet access for the playbooks and the documentation tools. Reading the device works without it.
Which SWTools build

The playbooks and the documentation tools (list_playbooks, get_playbook, search_docs, read_doc, doc_link) are not in 4.0.0-rc2 or its rc2.x fixes; they come with the next SWTools build. To check yours, ask the assistant which emGUI tools it has, or to call emgui_status. An older build still has all the device tools, without these five.

Connect your assistant​

  1. Start emGUI and connect to your device. Start emGUI before the assistant.
  2. Copy the server URL from emGUI and paste it into the field below. Or, in emGUI, click MCP → Getting started with AI assistants...: it opens this page with the URL already filled in.
  3. Pick your assistant and follow its steps.
Not possible: claude.ai, ChatGPT in the browser, Claude custom connectors

These run in the vendor's cloud, not on your PC, so they cannot reach emGUI. The same goes for the Claude mobile app and for Customize → Connectors → Add custom connector in Claude Desktop.

Use one of these instead: Claude Desktop (with the config file), Claude Code, Cursor, VS Code or the ChatGPT desktop app.

In emGUI, click MCP → Copy server URL and paste it here. The steps below use this URL.

Claude Desktop reaches emGUI through a small bridge, mcp-remote. It needs Node.js on your PC: install it first.

  1. In Claude Desktop, open Settings → Developer → Edit Config. This opens claude_desktop_config.json (Windows: %APPDATA%\Claude\, macOS: ~/Library/Application Support/Claude/).
  2. Add the emgui entry:
    claude_desktop_config.json
    {
      "mcpServers": {
        "emgui": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "http://127.0.0.1:28955/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 to %APPDATA%\Claude\logs\mcp*.log (macOS: ~/Library/Logs/Claude).

emGUI started with --mcp-token

Only if emGUI was started with --mcp-token. Then every request has to carry the token, or emGUI refuses it.

Typed here only to fill in the snippet. This page sends nothing anywhere.

Use this entry instead. Keep the header argument exactly as written, without spaces.

claude_desktop_config.json
{
  "mcpServers": {
    "emgui": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:28955/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_TOKEN"
      }
    }
  }
}

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.

What the assistant can do​

emGUI gives the assistant these tools:

  • Device tools: list the connected devices, read and write their values, and run commands. What they may change depends on the level below.
  • list_playbooks and get_playbook: siliXcon's diagnostic playbooks. The ones that match the connected device are marked.
  • search_docs: searches this documentation.
  • read_doc: reads a page of this documentation for the assistant, for example a table of values that a search hit or a playbook points to.
  • doc_link: finds the documentation page of one variable of the connected device.

The playbook and documentation tools need a recent emGUI build, see Requirements.

By default the assistant can only read. It can list devices, read values and run commands that change nothing. You decide whether it may do more:

Level in the emGUI MCP menuThe assistant may also
Read only (the default)Nothing more.
Allow writesChange parameters and run commands that change the device state.
Allow dangerous commandsRun commands that can move a motor or change the device address or its interface. For development only, with the hardware in sight.
  • To change the level, open the MCP menu, click Stop server, pick the level, then click Start server. Or start emGUI with --mcp-write=write or --mcp-write=danger.
  • emGUI never remembers the level. Every start is read-only, unless you start it with --mcp-write.
  • While writes are allowed, the emGUI window title says so: MCP: writes enabled or MCP: dangerous commands enabled.
  • The assistant cannot raise the level itself. A motor can move only at the highest level, and only if you chose it.

First things to ask​

  • "What is the reason the connected device is not running?"
  • "Which devices are connected, and which firmware do they run?"
  • "Read the error states of my controller and explain them, with links to the documentation."

Playbooks​

A playbook is a step-by-step diagnosis written by siliXcon engineers: which values to read first, what they mean and what to check next. emGUI downloads the current playbooks from this site when your assistant asks for them, so the assistant follows the same order of checks as our support does. The playbooks are ordinary pages, so you can read them too: AI playbooks.

Troubleshooting the connection​

The assistant does not see emGUI.

  • emGUI must be running, and it must be started before the assistant. If the assistant was already running, restart it (quit Claude Desktop completely), or reconnect the server from the assistant's list of MCP servers.
  • The server must be running. When it is, the MCP menu offers Stop server. If it offers Start server (and Copy server URL is greyed out), click Start server.
  • The port must match. When the server starts, the emGUI Log panel shows a line such as MCP server: http://127.0.0.1:28955/mcp (read-only). A second emGUI uses the next free port. Copy the URL again and update your assistant.
  • After you change the assistant's configuration, restart the assistant. Claude Desktop has to be quit completely.

emGUI was started with --mcp-token. Every request then has to carry the token, or emGUI refuses it. Each tab above has the token variant under emGUI started with --mcp-token. An assistant that cannot send the token cannot be used with it.

Browsers cannot connect. emGUI refuses requests from websites (anything not served from your own PC) on purpose, so that no website can control your device. That is also why this page cannot test the connection for you.

See what the assistant asks. In the MCP menu, click Stop server, tick Log requests and click Start server. Or start emGUI with --mcp-log. Every request and its result then appear in the Log panel. If nothing appears when you ask your assistant something, the assistant does not reach emGUI: check the URL.

Playbooks or documentation are "unavailable". They come from docs.silixcon.com. Without internet access the assistant tells you so and continues with what the device reports. emGUI keeps the playbooks it downloaded last and uses them while it is offline.

Documentation search without emGUI​

Not running emGUI, or only want answers from the documentation? Connect the public documentation search directly. It needs no account and no key. If your emGUI already has the documentation search (see Requirements), you do not need it.

https://docs.silixcon.com/mcp

This server is on the internet, so cloud assistants can use it too:

  • 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
  • Any other assistant from the tabs above: copy the snippet from its tab and change it by hand: silixcon-docs as the name and https://docs.silixcon.com/mcp as the URL. The field above accepts emGUI addresses only, and the one-click buttons install emGUI. Do not use the Claude Desktop config file for it; use Connectors as described above.

Not every client takes the same configuration. A generic {"mcpServers": {"name": {"url": ...}}} block works only in Cursor, Windsurf and JetBrains. It does not work in Claude Desktop, Claude Code, VS Code, Gemini CLI, Cline or Roo Code, and Zed uses context_servers instead: take the form from the client's tab.

It is a search tool, not an oracle

The assistant receives matching sections, not the whole documentation. It can miss context on a neighbouring page, 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.