brontes-probe-mcp

A Model Context Protocol (MCP) server that gives AI assistants direct access to a debug probe — flash firmware, halt/resume, read memory, and stream ITM trace, all without leaving the conversation.

Status: 0.3.0 — first-use hardened. Session lifecycle, probe operations, ITM/SWO trace (raw + decoded export), CMSIS pack-cache recovery, and lane supervision over three concurrent transports (stdio MCP, Unix socket, loopback TCP). All seven first-adopter friction points from the 0.2.2 retrospective are addressed — see CHANGELOG.md.

Quick start

Three steps: configure, start the probe agent (macOS / pip only), connect.

Step 1 — Configure

Pick your deployment. Each section below includes a prompt you can paste directly into Claude Code to write .mcp.json automatically, or add it manually if you prefer.

Docker on Linux (recommended)

Paste into Claude Code:

Add brontes-probe-mcp to .mcp.json in this project, creating it if needed:

{
  "mcpServers": {
    "brontes-probe-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--device=/dev/bus/usb",
        "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
        "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
        "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
        "-e", "CMSIS_PACK_ROOT=/packs",
        "ghcr.io/cms-pm/brontes-probe-mcp@sha256:61e4d0423085ac734a938b2a45a984e5197e1803326547f5d13d519e67798e91"
      ]
    }
  }
}

Then pull the image:
docker pull ghcr.io/cms-pm/brontes-probe-mcp@sha256:61e4d0423085ac734a938b2a45a984e5197e1803326547f5d13d519e67798e91

Then tell me to restart Claude Code to load the new server.

Replace sha256:61e4d0423085ac734a938b2a45a984e5197e1803326547f5d13d519e67798e91 with the digest from CHANGELOG.md.

Docker on macOS (Docker Desktop)

Docker Desktop cannot pass USB devices into containers. First install the host CLI:

pip install brontes-probe-mcp

Paste into Claude Code:

Add brontes-probe-mcp to .mcp.json in this project, creating it if needed:

{
  "mcpServers": {
    "brontes-probe-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
        "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
        "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
        "-e", "CMSIS_PACK_ROOT=/packs",
        "-e", "PROBE_BROKER_GDB_HOST=host.docker.internal",
        "ghcr.io/cms-pm/brontes-probe-mcp@sha256:61e4d0423085ac734a938b2a45a984e5197e1803326547f5d13d519e67798e91"
      ]
    }
  }
}

Then tell me to restart Claude Code to load the new server.

pip install (no Docker, all platforms)

Pre-flight checks — these three commands should succeed before you start the agent. They cover the friction points from real first-use:

# 1. pip is available (bootstrap with ensurepip if your venv was created without it)
python -m pip --version  ||  python -m ensurepip --upgrade

# 2. arm-none-eabi-gdb is on PATH (install via your OS package manager or
#    https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads)
arm-none-eabi-gdb --version

# 3. Install brontes-probe-mcp and confirm the console script is on PATH
pip install brontes-probe-mcp
brontes-probe-mcp-cli --version

If brontes-probe-mcp-cli is not found, your shell's PATH doesn't include the directory pip wrote the script to. Either re-source your venv activate script (source .venv/bin/activate) or use python -m brontes_probe_mcp / python -m brontes_probe_mcp.cli directly.

Paste into Claude Code:

Add brontes-probe-mcp to .mcp.json in this project, creating it if needed:

{
  "mcpServers": {
    "brontes-probe-mcp": {
      "command": "brontes-probe-mcp-cli",
      "args": ["serve"]
    }
  }
}

Then tell me to restart Claude Code to load the new server.

Step 2 — Start the probe agent (macOS and pip only)

Docker on Linux users skip this step — the container manages pyocd internally.

Run this once before each session (keep it running in the background):

# Auto-detects probe and target if exactly one probe is connected
brontes-probe-mcp-cli probe-agent start

If auto-detection fails (multiple probes, or board not recognised by pyocd):

brontes-probe-mcp-cli probe-agent start --target stm32g474 --probe-uid <uid>

session_start auto-discovers the running agent — no extra configuration needed. session_stop removes the Brontes session but leaves the agent running for reuse.

Step 3 — Connect

After restarting Claude Code (or running /mcp to reload), paste this into the conversation:

Call probe_discover to list connected debug probes. Use any board or chip
information from the results to call target_suggest and find the pyocd
target string — pyocd usually wants the full subfamily/package suffix
(for example "stm32g474ceux", not bare "stm32g474"). If target_suggest
returns no matches, call pack_update to refresh the pack index, then
pack_search to find the right CMSIS pack name, then pack_install (may
take a minute), then retry target_suggest. If pack_search or pack_install
fails with pack_index_corrupt, call pack_cache_reset to wipe and rebuild
the pyOCD pack index, then retry. Once you have the target string, call
session_start — omit probe_uid if only one probe is connected, otherwise
pass the uid from probe_discover. If you have a CMSIS pack on disk, you
can pass pack=/path/to/pack to bypass the global pack index entirely.

If you already know your target string and pack path (fastest path):

Call session_start with target="stm32g474ceux" and pack="/path/to/STM32G4xx_DFP".

What it does

• Probe discovery — probe_discover, target_suggest (with local-PDSC bypass), pack_search, pack_install, pack_update, pack_cache_reset (recover from corrupt pyOCD pack index).
• Session lifecycle — session_start, session_stop, session_status (reports image_digest, image_tag, protocol_version, session_id).
• Probe operations — probe_program (elf / bin / hex), probe_halt, probe_resume, probe_reset (soft, hard, sw, system, core, backend_default — each maps to a documented monitor reset command and the exact command is echoed back), probe_mem_read, probe_blackbox_export (explicit range required — see below).
• ITM / SWO trace — itm_stream_start, itm_stream_stop, itm_stream_export (raw bytes + decoded JSONL artifact), recent_lines (with session_id / method / lane filters).
• Lane supervision — lane_status, lane_release, lane_resume.

Three transport adapters bind concurrently over one shared BrokerCore instance, controlled by PROBE_BROKER_TRANSPORTS:

CLI

The brontes-probe-mcp-cli console script manages the server and probe agent:

brontes-probe-mcp-cli --version
brontes-probe-mcp-cli --config-dump            # print resolved config as JSON

# Start all configured transports (MCP server entry point for pip install)
brontes-probe-mcp-cli serve

# Probe agent — manages the host-side pyocd gdbserver daemon
brontes-probe-mcp-cli probe-agent start [--target TARGET] [--port PORT] [--probe-uid UID]
brontes-probe-mcp-cli probe-agent status       # prints JSON; exits 1 if not healthy
brontes-probe-mcp-cli probe-agent stop [--force]

# Generic one-shot JSON-RPC client over the running Unix socket
brontes-probe-mcp-cli call session_status
brontes-probe-mcp-cli call mem_read --json '{"addr":536870912,"length":4}'
brontes-probe-mcp-cli call session_start --json '{"target":"stm32g474ceux"}'

call opens a short-lived connection to the running broker's socket, sends one envelope, prints the reply, and exits. Exit codes: 0 on a non-error response, 1 on a transport failure or {"error": ...} envelope, 2 on invalid --json input.

If --target is omitted, probe-agent start auto-detects from a connected probe. If multiple probes are attached, specify --target and --probe-uid.

Configuration

All configuration is via PROBE_BROKER_* environment variables:

Flash memory snapshot (probe_blackbox_export)

Capture a binary snapshot of the target's memory for archiving or diff. As of 0.3.0 an explicit range is required — the previous 512 KB flash default took roughly four minutes for a 48-byte evidence slice, so we removed it. Pass exactly one of:

// (1) explicit start/end
{"tool": "probe_blackbox_export",
 "arguments": {"out": "/tmp/snapshot.bin",
               "start_addr": 134217728, "end_addr": 134742016}}

// (2) start + length
{"tool": "probe_blackbox_export",
 "arguments": {"out": "/tmp/snapshot.bin",
               "addr": 536870912, "length": 48}}

// (3) named region from the advisory registry (sram_blackbox = 0x20000000, 64 B)
{"tool": "probe_blackbox_export",
 "arguments": {"out": "/tmp/snapshot.bin", "region": "sram_blackbox"}}

Calling with none of those raises ValueError. Response includes bytes_written, snapshot_at (UTC ISO-8601), and resolved_addr / resolved_length / resolved_from_region recording exactly which range the call resolved to.

See docs/tutorials/blackbox-export.md for custom address ranges, error cases, and snapshot comparison examples.

Troubleshooting first-use

These are the friction points the 0.2.2 first adopter actually hit, with the fix path each one now has in 0.3.0:

Advanced deployment

Docker Compose (socket, auto-restart)

curl -fsSL https://raw.githubusercontent.com/cms-pm/brontes-probe-mcp/main/docker-compose.yml \
  -o docker-compose.yml
docker compose up -d

TCP loopback (sandbox / Docker Desktop without probe-agent)

docker run -d --name brontes-probe-mcp \
  -e PROBE_BROKER_TRANSPORTS=stdio,tcp \
  -e PROBE_BROKER_TOKEN=your-token-here \
  -p 127.0.0.1:7172:7172 \
  --device=/dev/bus/usb \
  ghcr.io/cms-pm/brontes-probe-mcp:0.3.0

Pinning by digest

Pin by digest for production — the digest is the binary-level reproducibility contract:

ghcr.io/cms-pm/brontes-probe-mcp@sha256:<digest>

Digests are published in CHANGELOG.md for each release.

Client configuration

Configure your AI client to launch the server via the MCP stdio transport.

Claude Desktop

Add the following entry to the mcpServers object in ~/Library/Application Support/Claude/claude_desktop_config.json (Linux: ~/.config/Claude/claude_desktop_config.json):

{
  "brontes-probe-mcp": {
    "command": "docker",
    "args": [
      "run", "--rm", "-i",
      "--device=/dev/bus/usb",
      "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
      "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
      "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
      "-e", "CMSIS_PACK_ROOT=/packs",
      "ghcr.io/cms-pm/brontes-probe-mcp@sha256:61e4d0423085ac734a938b2a45a984e5197e1803326547f5d13d519e67798e91"
    ]
  }
}

Claude Code

Add to .mcp.json in your project root (or ~/.claude.json for global config):

{
  "mcpServers": {
    "brontes-probe-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--device=/dev/bus/usb",
        "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
        "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
        "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
        "-e", "CMSIS_PACK_ROOT=/packs",
        "ghcr.io/cms-pm/brontes-probe-mcp@sha256:61e4d0423085ac734a938b2a45a984e5197e1803326547f5d13d519e67798e91"
      ]
    }
  }
}

Codex

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "brontes-probe-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--device=/dev/bus/usb",
        "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
        "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
        "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
        "-e", "CMSIS_PACK_ROOT=/packs",
        "ghcr.io/cms-pm/brontes-probe-mcp@sha256:61e4d0423085ac734a938b2a45a984e5197e1803326547f5d13d519e67798e91"
      ]
    }
  }
}

OpenCode

Add to opencode.json in your project root:

{
  "mcp": {
    "servers": {
      "brontes-probe-mcp": {
        "type": "stdio",
        "command": "docker",
        "args": [
          "run", "--rm", "-i",
          "--device=/dev/bus/usb",
          "-v", "${HOME}/.brontes-probe-mcp:/run/brontes-probe-mcp",
          "-v", "${HOME}/.brontes-probe-mcp/packs:/packs",
          "-e", "PROBE_BROKER_TRANSPORTS=stdio,socket",
          "-e", "CMSIS_PACK_ROOT=/packs",
          "ghcr.io/cms-pm/brontes-probe-mcp@sha256:61e4d0423085ac734a938b2a45a984e5197e1803326547f5d13d519e67798e91"
        ]
      }
    }
  }
}

Replace sha256:61e4d0423085ac734a938b2a45a984e5197e1803326547f5d13d519e67798e91 with the pinned digest from CHANGELOG.md.

Why "Brontes"

Brontes ("Thunderer") is one of the cyclops smiths in Hephaestus's forge — the worker who hammers metal at the master's direction. The metaphor maps onto the broker's role: client code directs the operation, the broker performs the probe work.

Changelog

See CHANGELOG.md.

License

Apache-2.0. See LICENSE.