MCP Server Overview

Every Lager Box runs an MCP (Model Context Protocol) server. It lets an AI agent understand the bench, understand the device under test (DUT), and plan hardware-in-the-loop tests. It runs on-box and is reachable over the box’s local IP. By default, the MCP server is read-only: it describes the bench and DUT, and it does not drive hardware or run code. Two opt-in environment variables change that; see Optional tool gates. The agent executes tests over a separate channel — the lager CLI.

MCP-compatible AI agent
    |  MCP (streamable-http via box IP)     ← discovery + planning (read-only)
    v
Lager MCP Server (on-box, port 8100)
    |  reads /etc/lager bench config (nets, DUT context, instruments)
    v
Bench / DUT metadata

AI agent  ──  lager python path/to/test.py --box <box-ip>  ──▶  Hardware
              (execution happens over the CLI, not MCP)

Connecting an agent

Point any MCP-compatible client at the box:

{
  "mcpServers": {
    "lager": {
      "url": "http://<box-ip>:8100/mcp"
    }
  }
}

Out of the box the MCP server is for discovery and planning only — it does not run code or drive hardware. Two opt-in environment variables extend it past that; see Optional tool gates. To execute a test, the agent writes a Python file locally. It then runs the file with lager python path/to/test.py --box <box-ip>, which syncs the project to the box and runs it with full project context. Pass the box’s IP address to --box — the same IP you connected to the MCP server on. Local box names are just client-side aliases, so the IP is the only identifier both sides can rely on. To make this concrete, discover_bench() echoes the address you actually connected on as box_address and hands back a ready-to-run lager python … --box <that-address> command.

The URL above assumes a box that publishes its ports, which is the default. A box started with start_box.sh --no-publish (or LAGER_NO_PUBLISH=1) does not publish port 8100 on the host. The MCP server still runs and binds 0.0.0.0:8100 inside the container. It is reachable only on the internal lagernet Docker network, where a reverse proxy owns the host ports. On such a box, point the client at the container’s lagernet address, because <box-ip>:8100 will not connect. Do not route port 8100 through the proxy, because the MCP server performs no authentication.The mode persists across restarts in /etc/lager/no_publish, and start_box.sh --publish clears it. At the end of each run, start_box.sh reports which mode the box is in.

What the agent sees

The server exposes two kinds of things: resources (read-only context the agent reads) and tools (callable functions).

Resources

Resource	What it gives the agent
`lager://dut/overview.md`	Read this first. A narrative briefing: what the box tests, the DUT MCU/peripherals, subsystems, and which documents to fetch.
`lager://dut/context`	The full DUT context as structured JSON.
`lager://bench/identity`	Box ID, hostname, version, and a per-DUT summary (purpose, MCU).
`lager://bench/netlist`	Every net with type, roles, instrument, and metadata.
`lager://bench/interfaces`	Protocol interfaces (SPI, I2C, UART) and their nets.
`lager://guide/overview`	What Lager is and what a “net” is.
`lager://guide/workflow`	The recommended orient → discover → plan → write → run loop.
`lager://guide/rtt-defmt`	The core firmware-log workflow: streaming RTT and decoding `defmt`. Covers the `dbg.session()` scope, the reconnect-aware RTT reader and self-healing `reset()`/`read_memory()` (so you don’t write flash/reset workarounds), and the DA1469x post-flash reconnect exception.
`lager://reference/{net_type}`	The full API reference for one net type as JSON (e.g. `lager://reference/Debug`) — methods, gotchas, and a runnable example snippet.
`lager://guide/api-quick-reference`	Compact `lager.Net` API cheat sheet by net type.
`lager://guide/docs`	Links to the full hosted docs (`docs.lagerdata.com`) and the `llms.txt` page index for anything not covered on-box.

Tools

Tool	Purpose
`discover_dut()`	One call for orientation: DUT purpose, MCU, peripherals, subsystems, and document references.
`discover_bench(net_name?)`	Enumerate hardware — nets, plus instruments with their channels, capabilities, and authored specs/ranges. With a net name, return that net’s full metadata, capabilities, parent subsystem, and relevant document references (and, if the net is unknown, the list of available net names).
`cite_schematic(net_name)`	Return just the schematic/datasheet references and page hints relevant to one net.
`plan_firmware_test(firmware_description, test_goals)`	Generate a phased test plan, scoped to relevant nets, with DUT context and document references attached.
`assess_suitability(test_type)`	Check whether the bench can run a given test type.
`get_test_example(query)`	Find runnable example scripts by net type, pattern, or keyword.
`box_manage(action)`	`health` check or `reload` the bench config from disk.

By default the tool surface is read-only. The seven tools above do not drive hardware (set a voltage, toggle a GPIO, flash firmware) or mutate the box. All of that lives in the test script the agent writes and runs with lager python, or in dedicated CLI commands.This default holds only while both gates below are off.

Optional tool gates

Two environment variables, both off unless explicitly set, register additional tools when the box’s MCP server starts. Each widens what a connected agent can do to the box, so treat them as deployment decisions rather than conveniences.

`LAGER_MCP_ALLOW_CONTROL`

Adds three scoped tools. These read bench state and power-cycle a hub port — they do not execute arbitrary code.

Tool	Purpose
`net_status(net)`	Compact read-only status for one net on the bench.
`debug_probe_status(net)`	Whether a debug net’s probe is present on the USB bus.
`power_cycle_hub(hub)`	Power-cycle one USB hub port (Acroname, YKUSH, or Plugable) with the same `cycle` as `lager usb`, holding the port off for 1 second. The result carries `reconnected`: `true`, `false`, or `null`. The tool waits 4 more seconds only when the box cannot read its USB topology. Drives hardware.

`LAGER_MCP_ALLOW_EXEC`

This gate exposes arbitrary command execution and file writes on the box to any agent that can reach the MCP port. An agent can run any command the box’s service user can run, and overwrite any file it can write. The server itself logs a warning at startup when this is set. Enable it only on a bench you control, on a trusted network, and never on a shared or production box.

Tool	Purpose
`box_exec(command, timeout_s, cwd)`	Run an arbitrary shell command on the box and capture its result.
`read_file(path, max_bytes)`	Read a file on the box (config, source, logs).
`write_file(path, content)`	Atomically write a file, backing up any prior version.
`list_dir(path)`	List the entries of a directory on the box.

Prompts

The server also registers a few prompts. These are slash-command-style entry points that steer a client (e.g. Cursor) through the discover → plan → write → run workflow. They do no work themselves. Each returns an instruction that the agent follows with the tools above.

Prompt	What it does
`write_lager_test(what_to_test)`	Walks the agent through discovering the bench/DUT, planning, writing a test, and running it over the CLI.
`explore_bench()`	Orients on what the box is, what it tests, and what it can run.
`assess_test_feasibility(test_description)`	Checks whether the bench has the capabilities for a described test.

The recommended agent workflow

Orient

Read lager://dut/overview.md (or call discover_dut()) to learn what the box tests, the MCU and peripherals, the subsystems, and which documents to fetch.

Discover

Call discover_bench() to enumerate nets, instruments, and capabilities. Call discover_bench(net_name) for detail on a specific net, including its subsystem and the schematic sheet it lives on.

Plan

Call plan_firmware_test(...) to get a phased plan with API references and document pointers per step.

Write & Run

Author a Python test file using from lager import Net, NetType. Identify the box by the IP address you connected to the MCP server on — local box names are arbitrary client-side aliases. --box accepts a raw IP, so no registration is needed: run lager python path/to/test.py --box <box-ip>. The runnable can also be a folder (entrypoint main.py), which syncs and imports everything in it — handy for shipping reusable helper modules: lager python path/to/test_dir --box <box-ip>. (Optionally, lager boxes add --name <name> --ip <box-ip> --user <ssh-user> registers a friendly alias; all three options are required.)

Analyse & iterate

Review the CLI output, adjust the script, and re-run it with lager python.

Where context comes from

The quality of everything above depends on the metadata you author once, at bench setup:

Per-net purpose — set in the Net Manager TUI (lager nets tui), or with lager nets describe NAME --purpose "...". One sentence describing what each wire does on the DUT.
DUT context — set with lager dut: the box’s purpose, MCU, subsystems, and references to schematics and datasheets.

See Authoring DUT Context for the full guide.

​Connecting an agent

​What the agent sees

​Resources

​Tools

​Optional tool gates

​LAGER_MCP_ALLOW_CONTROL

​LAGER_MCP_ALLOW_EXEC

​Prompts

​The recommended agent workflow

​Where context comes from

Connecting an agent

What the agent sees

Resources

Tools

Optional tool gates

`LAGER_MCP_ALLOW_CONTROL`

`LAGER_MCP_ALLOW_EXEC`

Prompts

The recommended agent workflow

Where context comes from