embeddedci-mcp

An MCP server that lets an AI agent drive an EmbeddedCI BenchPod — a hardware-in-the-loop tester wired to a real board. Ask Claude (or any MCP client) to flash a build, power-cycle the target, watch its UART, pretend to be the sensor it expects, probe its I2C/CAN traffic or drive and measure analog signals, and the pod does it.

It is a thin layer over the embeddedci SDK: every tool maps to SDK calls, so anything an agent discovers interactively can become a pytest test.

Requirements

• Python 3.10+ and uv (for uvx), or pip.
• A BenchPod reachable over the network or the embeddedci.com cloud. (A USB connection works for status, LA voltage and power only: the STM32 pod's USB console has no JSON mode.)
• For flash: OpenOCD with the cmsis_dap_tcp backend (newer than 0.12.0 — e.g. brew install --HEAD open-ocd, or the xPack build) on the machine running the server. The firmware file is read from that machine too. Flashing a build uploaded to embeddedci.com (build/repo/ref) over a cloud connection needs neither: embeddedci.com runs OpenOCD.

Set up your client

Claude Code

claude mcp add benchpod \
  -e BENCHPOD_CONNECTION=192.168.1.213 -e BENCHPOD_LA_VOLTAGE=3.3 \
  -- uvx embeddedci-mcp

BENCHPOD_LA_VOLTAGE is the board's I/O voltage, configured once here — use 1.8 for a 1V8 board. Without it the agent is told to call set_la_voltage before touching the LA bank.

Both variables are optional. connect picks the pod, first match wins:

1. its connection argument;
2. the server default, --connection;
3. BENCHPOD_CONNECTION;
4. the default connection benchpod-cli saved with benchpod set-connection <address|device|usb> (read-only, from ~/.config/benchpod-cli/config.json, or under $XDG_CONFIG_HOME);
5. mDNS discovery of the one pod on the LAN.

So the CLI, the SDK and the MCP server share one saved connection. With none of the first four, connect looks for a BenchPod on the LAN over mDNS (like discover) and uses it when it finds exactly one. When it finds none or several, the error lists the pods it heard (name and address) and what to pass instead: host[:port], usb, or embeddedci:<device> for a cloud pod (cloud_list_devices lists those). So claude mcp add benchpod -- uvx embeddedci-mcp is enough for a single pod on your network: just ask the agent to connect.

Claude Desktop / Cursor

claude_desktop_config.json (Claude Desktop) or .cursor/mcp.json (Cursor):

{
  "mcpServers": {
    "benchpod": {
      "command": "uvx",
      "args": ["embeddedci-mcp"],
      "env": {
        "BENCHPOD_CONNECTION": "192.168.1.213",
        "BENCHPOD_LA_VOLTAGE": "3.3"
      }
    }
  }
}

Codex

The Codex CLI keeps its MCP servers in ~/.codex/config.toml. Add it with the CLI:

codex mcp add benchpod \
  --env BENCHPOD_CONNECTION=192.168.1.213 --env BENCHPOD_LA_VOLTAGE=3.3 \
  -- uvx embeddedci-mcp

…or write the entry yourself (codex mcp list shows what is configured):

# ~/.codex/config.toml
[mcp_servers.benchpod]
command = "uvx"
args = ["embeddedci-mcp"]
env = { BENCHPOD_CONNECTION = "192.168.1.213", BENCHPOD_LA_VOLTAGE = "3.3" }

A pod in the cloud

Use the device name and an API key — the cloud transport is included:

"env": {
  "BENCHPOD_CONNECTION": "embeddedci:my-bench",
  "BENCHPOD_API_KEY": "eci_…",
  "BENCHPOD_LA_VOLTAGE": "3.3"
}

Or skip the API key: after benchpod login, the server reuses that session (~/.config/benchpod-cli/token.json, refreshed and written back when it has expired) for cloud_list_devices, connect("embeddedci:<name>") and, on a LAN or USB connection, the pod's stored wiring profile. BENCHPOD_API_KEY wins when set, and inside GitHub Actions the SDK uses OIDC instead.

cloud_list_devices lists the pods on your account and which are online, without connecting to one; pass a result's connection to connect. The session token behind a cloud connection is renewed before it expires, so a long session keeps working.

A cloud pod is shared, so connect takes an exclusive lease (waiting up to --lease-wait seconds if another run holds it). The lease is released by disconnect, or after --idle-timeout seconds without a tool call — the next call reconnects transparently, so an idle chat never blocks CI on that pod.

Options

Serving a bench over HTTP

Run the server on the machine next to the pod, and point clients at it:

export EMBEDDEDCI_MCP_TOKEN=$(openssl rand -hex 32)
embeddedci-mcp --transport http --host 0.0.0.0 --connection 192.168.1.213 --la-voltage 3.3

claude mcp add --transport http benchpod http://bench-host:8000/mcp \
  --header "Authorization: Bearer $EMBEDDEDCI_MCP_TOKEN"

The server drives real hardware, so it refuses a non-loopback bind without a token. It holds one pod connection shared by all HTTP clients, and serialises their tool calls.

Tools

Every tool, grouped as in the server. Parameters in bold are required; the others are optional and show their default when they have one (no default means "from the wiring profile", "keep the current setting" or "not used"). Units are volts, amps, seconds and hertz. LA channel arguments take a number (1-14) or a name from the wiring profile. Each tool's input schema carries the full description, ranges and enums, so an agent sees more than this table.

Connection

Cloud (embeddedci.com)

Wiring profile

Power

Power profiles

Flash

SPI flash and SPI devices

UART

Emulated I2C sensor

Emulated GPS receiver

NMEA sentences (u-blox style: RMC VTG GGA GSA GSV GLL) on one LA channel for the DUT's UART, from the pod's second UART, so uart_open keeps the console. Needs gateware v48 (gps capability).

Pull resistors

GPIO on the LA pins

Analog

Capture and decode

DAC

Control loop

CAN

Other

Resources: benchpod://wiring (the connected bench's own wiring profile, then LA channels, bias resistors and analog paths) and benchpod://help (the server instructions).

How it behaves

• Instructions. The server sends usage instructions at initialisation — session start, typical flows, units, error contract — so the agent knows to connect and set_la_voltage before anything else.

• Typed, structured results. Every tool has an input schema with enums and ranges (paths, sources, LA channels 1-14, internal 5 V (efuse 1) or external (efuse 2), …) and an output schema; results come back as structured content. Units are volts, seconds and hertz.

• Errors. A tool that cannot do what was asked fails with an MCP tool error whose message names the cause, e.g. FirmwareError: la voltage not set or NotConnectedError: …. A completed operation with a negative outcome is a normal result: flash returns ok: false with its logs, a UART capture matched: false.

• Refusals. When the pod or the server refuses a command, the error names the kind and ends with a one-line hint on what to do: PodLockedError (the pod's LAN policy keeps the command for the cloud or USB), PodLeasedError (a cloud job holds the pod; the message names who and for how long), PodBusyError (a capture or upload is running), PermissionDeniedError (the credential lacks the right, for example an API key without the benchpod:admin scope) and TransportTimeout (the pod did not answer). A dropped link is a ConnectionClosedError. UnsupportedFeatureError means the pod cannot do it at all: its firmware or gateware lacks the feature, or it is the digital-only board without the analog front end; the hint says which. status also warns when a cloud job holds the pod or the LAN policy is locked. Refusals whose fix the firmware spells as a raw protocol command name the tool instead: FirmwareError: uart_proxy_start: la voltage not set; call set_la_voltage first with the DUT's I/O voltage (1.8 or 3.3) and PinConflictError: uart_proxy_start: pin conflict: LA4 is in use by gpio; release it with gpio_release(la=[4]). The other pin owners point to uart_close, disable_i2c_sensor and disable_gps; a pull conflict to set_pull(las=[7], enabled=false).

• Capabilities. connect and status report what the pod can do as flags, so an agent can check before it calls a tool: for example la_pins, capture_trigger, power_profile, nrst_pin, can, calibrate, current_out, pod_current and analog (false on the digital-only board), plus the pod's policy and cloud settings (dac_limits, flash_kb, ota_sig, sig_policy, lan_policy, tunnel_max_tier, lease_state, cloud_ca, cloud_proxy).

• Wiring profile. wiring is the bench's map of DUT signal → LA channel, plus the target-power rail, the UART baud and the SWD target. Omitted channel / baud / rail / SWD arguments come from it, and channel arguments also accept its names (trigger_la: "READY", rx: "uart_rx"), so an agent that read wiring once can call flash(), uart_open() or power_on() with no pin numbers at all. set_wiring replaces it for the connection, or stores it on embeddedci.com with save: true.

  It is the same profile the web UI's Wiring tab edits. The SDK resolves it, first match wins: BENCHPOD_WIRING (a file); the profile stored on embeddedci.com for this pod (a cloud pod by name; a LAN or USB pod by the device it reports it is registered as, when BENCHPOD_API_KEY or the benchpod login session is available and that device is on the same account); the defaults. wiring and connect/status (wiring_source) report where it came from: server, file, dict (from set_wiring) or defaults. When the lookup fails (not signed in, pod not registered, server unreachable, another account) the defaults apply and nothing fails; over the LAN or USB it gives up after about 3 seconds. The STM32 pod's USB text console cannot report its registration, so over USB the defaults apply. BENCHPOD_WIRING_SOURCE=local skips the lookup.

• Agent-sized captures. capture_adc returns calibrated statistics, the dominant frequency and a min/max envelope; capture_la returns per-channel levels, edges and frequencies. The last captures stay in the session, so decode_la, replay(from_last_capture=true) and save_capture_as_recording don't capture again.

• Triggered captures. capture_adc, capture_la and capture_correlated take trigger_la (+ trigger_edge rising/falling/high/low and trigger_timeout) so sampling starts on an event — t = 0 is the trigger — and the summary echoes it as trigger: "LA9 rising". A condition that never happens fails with TriggerTimeout: ….

• Pins and GPIO. Each LA channel has one owner at a time: none, GPIO, a UART proxy, SWD, the emulated sensor or a step train. la_pins shows the table, gpio_mode / gpio_write / gpio_read / gpio_wait / gpio_pulse drive and watch channels, gpio_release frees them. A second claim fails with PinConflictError: pin conflict: LA5 is in use by uart_rx; … naming the owner and how to free it — so the agent releases GPIO before opening a UART session on that channel. Captures observe all 14 channels whatever owns them.

• Power profiles. measure_power(duration) reports average, minimum and peak current, voltage, energy and charge. Every sample is timestamped and the integrals run over those timestamps, so energy is integrated rather than estimated. rate_hz (100-500, default 500) tracks the request to ~200 Hz and then flattens near 365 Hz — the result reports the rate actually delivered in rate_hz and the sensor's configured rate in adc_rate_hz. Optional downsampled trace (points). power_profile_start / power_profile_stop bracket other tool calls; the running profile lives on the session (status reports it) and is dropped on disconnect.

• Sessions. uart_open buffers the DUT's console in the background (open it before power_on, then uart_read / uart_write); can_open keeps a CAN bus open across calls.

• Gateware images. The pod's FPGA runs either the loop image (control_loop) or the deep_replay image (replays longer than 2048 samples). control_loop, replay and replay_waveform switch automatically (~3 s) and report it as switched_image; switch_image: false fails instead. A switch resets the FPGA — a running DAC output, UART session or I2C sensor emulation stops — and the server instructions tell the agent to start those after it. fpga_image switches explicitly.

• Non-blocking. Tools run on worker threads under one device lock: a 5-minute flash doesn't freeze the server, sends progress notifications, and concurrent calls can't interleave commands.

• Annotations. Read-only tools (status, power_status, adc_read, …) are marked so clients can auto-approve them; tools that power, flash or drive voltages are marked destructive.

Example

Connect to the bench, flash build/app.elf to the STM32F4 (SWCLK on LA11, SWDIO on LA12, reset wired), then power-cycle it and tell me whether it reaches APP_OK on the UART (DUT TX on LA5, RX on LA4).

connect()                                   # BENCHPOD_CONNECTION + BENCHPOD_LA_VOLTAGE
flash(swclk=11, swdio=12, nreset=true, target="target/stm32f4x.cfg", file="build/app.elf", target_power=1)
power_cycle_and_capture(rx=5, tx=4, delay=1.0, duration=5.0, until_regex="APP_OK")

With a wiring profile stored for the bench, the same run needs no pin numbers:

connect()
wiring()                                    # SWCLK on LA11, DUT TX on LA5, rail internal 5 V (efuse 1), …
flash(file="build/app.elf")
power_cycle_and_capture(delay=1.0, duration=5.0, until_regex="APP_OK")
measure_power(duration=2.0, points=100)     # what the firmware draws once it is up

Stability

2.x freezes the tool names, input schemas and annotations (tests/tools_surface.json; CI fails on any unreviewed change): tools and optional parameters may be added, nothing is renamed or removed within a major version. See CHANGELOG.md for migrating from 0.1.

Publishing to the MCP Registry

server.json describes this package for the MCP Registry. The embeddedci-mcp-v* release workflow publishes it after the PyPI upload (which is what makes uvx embeddedci-mcp work), logged in with GitHub OIDC. Bump both version fields in server.json together with pyproject.toml: the release fails when they differ, and so does CI.

To publish by hand instead:

mcp-publisher login github
mcp-publisher publish

The registry verifies PyPI ownership through the mcp-name comment at the top of this README.

Development

pip install -e "../embeddedci[dev]" -e ".[dev]"
pytest