Built-in MCP server

An MCP server for your serial port

Termethos runs a Model Context Protocol server on your computer, so AI coding agents can read what your device prints, watch the live dashboard and send commands through the connection you have open. It can even set up the connection for a new board. The agent can check its own firmware change on the real board, without you copying logs back and forth.

Download Termethos Set it up

Turn on the MCP server

Click the AI agents (MCP) button in the toolbar.
Check Allow AI agents to connect, then choose what agents may do (see Permissions).
Keep the default port 7471 on 127.0.0.1, or pick another one, and click Save.

The dialog shows the setup command for Claude Code with your port and token already filled in. The MCP item in the status bar shows whether the server is off, listening, or in use by an agent.

Add Termethos to your agent

Termethos speaks MCP over Streamable HTTP at http://127.0.0.1:<port>/mcp, and every request needs the header Authorization: Bearer <token>. Use the port and token from the dialog; the examples use the default port.

Claude Code

Copy the command from the dialog and run it in a terminal. Full Claude Code guide

terminal

claude mcp add --transport http termethos http://127.0.0.1:7471/mcp --header "Authorization: Bearer <token>"

Cursor

Add Termethos to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project.

mcp.json

{
  "mcpServers": {
    "termethos": {
      "url": "http://127.0.0.1:7471/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

VS Code

Add Termethos to .vscode/mcp.json in your project, then use it from Copilot Chat in agent mode.

.vscode/mcp.json

{
  "servers": {
    "termethos": {
      "type": "http",
      "url": "http://127.0.0.1:7471/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Other MCP clients

Any client that can connect to a remote MCP server over Streamable HTTP and send a custom header works. Give it:

URL: http://127.0.0.1:7471/mcp
Header: Authorization: Bearer <token>

Token in a file? The token lets programs on your computer use Termethos. Don't commit an mcp.json that contains it. If it was shared, click New token in the dialog and update your agent.

Tools

These are the tools Termethos gives agents. Tools marked in yellow change something on your device or in Termethos; the others only read.

Tool	Parameters and result
`get_status`	Connection state, the active connection and its serial settings, simulation or device mode, number of trace lines, the current cursor, and what agents are allowed to do.
`list_connections`	Your saved connections and which one is active.
`read_trace`	Lines from the device, newest last, each with an id, receive time and level. `level` returns that level and above. Also returns a cursor and any partial line, such as a shell prompt. `lines` 1–2000 (default 100), `since` cursor, `level` all · info · warning · error, `search` regex
`wait_for_trace`	Waits until a matching line arrives, such as a boot banner after a reset, and returns it. `pattern` regex, `timeoutMs` up to 60000 (default 10000), `since` cursor
`read_dashboard`	The 24 dashboard fields (a 3 × 8 grid), each with its value and when it last changed, and which field changed last.
`send_command`	Sends a command with your connection's line ending, as if typed in Termethos, and returns the lines received while it waits. `command` up to 1000 characters, `waitMs` up to 10000 (default 0)
`list_quick_commands`	Your quick commands, with their command, description, hotkey and whether they run a script.
`run_quick_command`	Runs a quick command by name, like clicking its button. Commands that run a script need scripts to be allowed. `name`
`clear_trace`	Clears the trace, like the toolbar button. Line ids keep counting.
`connect`	Opens the active connection, or switches to another saved one first, and waits until it's connected or has failed. `connection` name (optional)
`disconnect`	Closes the connection, for example so a flash tool can use the port.
`create_connection`	Adds a connection and saves it. Settings not given default to 115200 bps, 8 data bits, no parity, 1 stop bit and no flow control. Open it with `connect`. `name`, and any of `portName`, `bitsPerSecond`, `dataBits`, `parity`, `stopBits`, `flowControl`, `dtr`, `rts`
`update_connection`	Changes the port or serial settings of a saved connection and saves them. Other settings stay as they are. Disconnect first to change the open connection. `name`, and the settings to change

Levels come from the !I, !W and !E prefixes your firmware prints, and dashboard values from @{id:value}. Agents can send up to 10 commands a second.

Permissions

All of these are in the AI agents dialog and apply right away.

Setting	Default	What it allows
Allow AI agents to connect	Off	Starts the MCP server. Agents with the token can read the trace, the dashboard, the connections and the quick commands.
Allow sending commands and running quick commands	On	Agents can use `send_command` and `run_quick_command`. Turn it off for read-only agents.
Allow quick commands that run scripts	Off	Agents can also run quick commands that run a JavaScript script. Termethos still asks you before a script runs the first time.
Allow connecting and disconnecting	Off	Agents can open and close the connection, and switch to another saved connection while disconnected.
Allow creating and changing connections	Off	Agents can add connections and change their port and serial settings with `create_connection` and `update_connection`. They're saved like the ones you create.

Security: you stay in control

Local only. The server listens on 127.0.0.1, so other computers can't reach it. Requests that name another host are refused, which blocks web pages from reaching it through DNS rebinding.
Token required. Every request needs your token. Click New token if it was shared.
Off by default. Nothing listens until you check Allow AI agents to connect.
Visible. Commands from agents show in the command history as [agent] <command>, and the MCP status item turns green while an agent is using Termethos.
Scripts ask first. Scripts have full access to your computer, so Termethos shows a script and asks before it runs the first time, and again if the script changes.

Termethos doesn't send your serial data anywhere. The agent you connect sends what it reads to its own model provider, like the rest of your code, so keep secrets out of your debug output.

Reading only new lines

Every trace line has an id. Each result returns a cursor; pass it back as since to get only lines received after it. That's how an agent checks a reset without re-reading the whole log:

tool calls, in order

get_status                                     // note the cursor, e.g. 18342
run_quick_command  name: "Reset board"
wait_for_trace     pattern: "ready", since: 18342, timeoutMs: 15000
read_trace         level: "warning", since: 18342   // warnings and errors since the reset

Troubleshooting

The agent can't connect

Check that Allow AI agents to connect is on and the status item says it's listening. If the port is used by another program, pick another port in the dialog and update the URL in your agent.

401 Unauthorized

The token in your agent doesn't match. Copy the command or token from the dialog again. Clicking New token makes old tokens stop working.

The agent's flash tool says the port is busy

Termethos has the serial port open. Allow connecting and disconnecting, and ask the agent to call disconnect before flashing and connect afterwards. Example

Commands go to the simulated device

Termethos is in simulation mode. Activate a license and agent commands go to your real board.

Try the MCP server with your agent

Download Termethos and connect your agent to simulation mode for free. A one-time $24.50 license sends its commands to your real board.

Download Termethos Buy $24.50