BYO Server
BYO Server is a local MCP server for guarded embedded-board setup, debugging, serial I/O, firmware deployment, and recovery via pyOCD.
Connect to debug probes by unique ID, target, or board config, and disconnect sessions.
Inspect board facts and core state: halt, resume, step, reset, read/write core registers.
Read and write memory with bounded addresses, including block reads and ELF symbol resolution.
Set and remove hardware/software breakpoints.
Capture and send bounded UART serial data with board-aware port resolution.
Flash approved firmware artifacts, optionally leaving the target halted after reset.
Run destructive unlock/recover flows only with explicit confirmation.
Query per-board safety tiers, setup status, and capabilities; choose raw or guarded operation routes.
Support discovery hooks and isolate monitor output under a dedicated monitor root.
Provides a Sentry monitor/logger integration for capturing and reporting server monitoring and logging data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BYO Server flash firmware to nrf52833dk"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
# BYO Firmware MCP
BYO Firmware MCP is a local, stdio-based MCP server for guarded embedded-board setup, inspection, serial I/O, debug control, firmware deployment, and recovery through pyOCD.
Current state
The server implementation lives in src/pyocd_debug_mcp. It is distributable
without bundled board profiles, firmware, packs, generated reports, or hardware
state. Board-specific state is created in the firmware project's .firm/
directory, never in this server checkout.
The server is intentionally headless and client-neutral. It exposes its current tool surface through the MCP protocol; a visible tool is not, by itself, authorization for a guarded operation.
Related MCP server: dbgprobe-mcp-server
Run
Install the locked environment:
uv sync --lockedStart the stdio server:
uv run --locked pyocd-debug-mcpRegister this command with an MCP-compatible client, preferably from the firmware project's directory:
uv run --project <absolute-path-to-BYO-Firmware-MCP> --locked pyocd-debug-mcpIf the client does not start the server from the firmware project, set
BYO_MCP_ARTIFACT_ROOT to that project's absolute path. Do not point it at this
repository.
To isolate passive monitor records for one launch, set
BYO_MCP_MONITOR_ROOT to an absolute directory before starting the server:
BYO_MCP_MONITOR_ROOT=/absolute/path/to/byo-monitor uv run --locked pyocd-debug-mcpA nonblank monitor root is exclusive: server_data/ and simulated_remote/
are created beneath it, never beneath per-user app data or the artifact root.
If that directory cannot be resolved or written, monitoring buffers in memory;
server startup and hardware behavior continue normally.
Server documentation
Server guide: setup, tool workflow, and safety model.
Architecture: runtime and state ownership.
Client contract: MCP behavior and response contract.
Plan-tool contract: guarded-operation plan fields.
Sentry evidence: final passing test suite, specifications, plans, and recorded results for the Sentry monitor/logger work.
Firmware MCP capabilities
Tiered capability routing
Each named logical board has an explicit project-local safety tier. A newly
named board is no-setup: use connect (optionally with its explicit
probe_uid or target) and the *_raw tools when the operator deliberately
owns unbounded-address risk. setup-lite adds confirmed coarse map containment
and retains raw escape hatches; every lite raw response instructs the agent to
display that bypass warning to the human. setup-full preserves the existing
validated/guarded workflow and refuses new raw routes.
Use get_capabilities(board_id) or get_setup_status(board_id) before acting;
both report the per-board tier, policy status and authoritative project root.
An incomplete initial setup (or a post-downgrade no-setup policy) remains raw.
An interrupted escalation from lite or full retains its prior active tier and
records the incomplete attempt separately. A corrupt committed policy is never
treated as raw and must be repaired before hardware access.
$downgrade and $mass-erase are manual-only workspace skills. The server
uses their project-local grants under .agent-workspace/runtime/manual-permissions,
resets those grants at every startup, and consumes each authorization once. Ask
the human to invoke the named skill; do not create or edit a grant directly.
Mass erase reserves that exact disclosure before plan acceptance and consumes it
before the backend call; a cancelled, changed, or failed plan discards the old
grant and requires a fresh skill invocation.
Raw memory, flash, and UART routes are deliberately bounded: raw serial reads, writes, exchanges, payloads, and captured output have finite operation limits. Existing planned full UART behavior is preserved. Lite safe routes require the explicitly confirmed region/config/backend facts for that operation; full safe routes additionally retain their normal live identity and plan prerequisites.
The server provides a guarded board-development surface:
Board readiness: discover connections, route familiar board names to validation or setup, establish board profiles, validate live hardware, and report readiness. When a machine cannot enumerate a debugger or serial port natively, an agent can author a local discovery hook under the project's
.firm/discovery_hooksso the server can see it; hook output names hardware and grants no authority.Debug and inspection: inspect board, CPU, execution, symbol, and bounded-memory state; control breakpoints, stepping, reset/run, and other bounded diagnostic actions.
Serial evidence: capture UART output and run controlled serial exchanges for declared tests or diagnosis.
Firmware deployment: bind the selected build output in a flash plan, verify it against the reviewed stable map at execution time, and flash the approved application. A successful flash is deployment evidence, not proof of behavior.
find_symbol, read_memory_symbol, and symbol-backed write_memory accept the current project's
ELF explicitly. Pass elf_artifact after a server restart; within one uninterrupted Server Run, a
successful application flash also creates a temporary convenience binding. The server never swaps
in implicit checkout firmware as another project's symbol table, and symbol addresses remain
subject to the board's memory-map containment policy.
Guarded mutation and recovery: writes, execution changes, bootloader work, and recovery require the current board gate, the exact
*-planaction, and any required human permission.Per-board safety: validation, plans, permissions, budgets, and results never transfer between connections. Disconnects and new server runs require validation; stable-map problems use the server's refresh path.
Always follow live MCP guidance. Visibility is not authorization: guarded actions use an all-null
*-plan guidance call, the returned populated plan submission, then the paired action.
Included command-line utilities
uv run --locked pyocd-pack-repair --help
uv run --locked pyocd-native-build --help
uv run --locked pyocd-collect-artifacts --helpPortable native-build artifacts
The server does not require a particular IDE or build system. Build with the project's native
tooling, then optionally normalize its explicit outputs with the small collector
(pyocd-collect-artifacts, above).
Historical implementation notes, progress material, test material, and generated
runtime state are kept outside the server in ../archive/BYO-Firmware-MCP-20260731/.
Available Tools
20 toolsconnectA
Open a debug session to a connected probe.
Args:
unique_id: Whole or partial probe serial/unique ID to select a specific
probe. Omit when exactly one probe is attached. Defaults to the
``PYOCD_PROBE_UID`` environment variable if unset.
target: Target type override, e.g. "stm32f407vg" or "nrf52833". Takes
precedence over a board config. Omit to use the selected board's
target (when ``board_id`` is given), else the ``PYOCD_TARGET``
environment variable, else pyOCD auto-detection.
board_id: Load facts from ``boards/<board_id>.yaml`` through the shared
board-config loader — pyOCD target, recover policy, silicon id, baud.
Lets a custom ST/nRF board connect by id with no hand-passed target;
call ``get_board_info`` to see the loaded facts. Defaults to the
``PYOCD_BOARD_ID`` environment variable.
board_config: Path to an extra board-config file outside the tracked
``boards/`` directory, for a custom board. Defaults to the
``PYOCD_BOARD_CONFIG`` environment variable.
Inputs: target, board_id, unique_id, board_config. Returns: result
disconnectA
Close the active debug session and release the probe.
Inputs: no named parameters. Returns: result
flash_firmwareA
Flash firmware through the shared target-control service layer.
Args:
path: Optional explicit artifact path. When omitted, resolve the default
flash artifact for the connected session's loaded board config.
Returns the resolved path in the success text.
halt_after_reset: If True, leave the target halted after flashing.
If False, reset and let it run.
Inputs: path, halt_after_reset. Returns: result
get_board_infoA
Return the facts from the board config the session was opened with.
Reports the ``boards/<board>.yaml`` definition active for this session —
pyOCD target, MCU and probe family, recover policy, silicon-id expectation,
default UART baud, and the smoke-test read address. Returns a notice when
``connect`` was called without a ``board_id`` (raw-target mode), where these
facts were not loaded.
Inputs: no named parameters. Returns: result
get_stateA
Return the current core run state (e.g. HALTED, RUNNING, RESET).
Inputs: no named parameters. Returns: result
haltB
Halt the core.
Inputs: no named parameters. Returns: result
read_core_registerA
Read a core register by name (e.g. "pc", "sp", "r0", "xpsr").
Returns the value as a hex string.
Inputs: name (required). Returns: result
read_memoryA
Read a single value from memory.
Args:
address: Memory address, hex (0x...) or decimal.
word_size: Transfer size in bits: 8, 16, or 32.
Inputs: address (required), word_size. Returns: result
read_memory_blockB
Read length bytes from memory starting at address.
Returns the bytes as a space-separated hex string.
Inputs: length (required), address (required). Returns: result
read_serialA
Capture bounded UART output through the shared serial-resolution and UART services.
Defaults come from the connected board config only for baudrate and
serial-port selection heuristics. ``expected_text=None`` means no explicit
text expectation: any observed UART output counts as a match.
Set ``port`` to override serial resolution explicitly. Set ``reset_on_open``
to trigger a target reset immediately after the UART port opens so early
boot text is captured deterministically.
Inputs: port, baudrate, read_seconds, expected_text, +1 more. Returns: result
read_symbol_u32B
Resolve symbol_name in elf_path and read its 32-bit value from target memory.
Inputs: elf_path (required), symbol_name (required). Returns: result
remove_breakpointB
Remove the breakpoint at address.
Inputs: address (required). Returns: result
resetA
Reset the target.
Args:
halt_after: If True, halt at the reset vector (reset-and-halt).
If False, reset and let the target run.
Inputs: halt_after. Returns: result
resumeC
Resume execution of the core.
Inputs: no named parameters. Returns: result
set_breakpointC
Set a hardware/software breakpoint at address.
Inputs: address (required). Returns: result
stepB
Single-step one instruction and return the new program counter.
Inputs: no named parameters. Returns: result
unlock_recoverA
Run the shared recover/unlock path for the connected board.
This is a destructive action. When ``confirm`` is false the tool refuses
without touching hardware. Boards whose tracked config has no supported
``recover_mode`` fail deterministically instead of pretending success.
Inputs: confirm. Returns: result
write_core_registerB
Write a core register by name. value may be hex (0x...) or decimal.
Inputs: name (required), value (required). Returns: result
write_memoryA
Write a single value to memory.
Args:
address: Memory address, hex (0x...) or decimal.
value: Value to write, hex (0x...) or decimal.
word_size: Transfer size in bits: 8, 16, or 32.
Inputs: value (required), address (required), word_size. Returns: result
write_serialA
Write bounded UTF-8 text to the connected board UART.
The tool uses the same board-aware serial-port resolution as ``read_serial``.
It never executes host commands and only writes bytes to the resolved UART
transport for the active connected session. Set ``port`` to override serial
resolution explicitly. Set ``append_newline`` when the target firmware
expects line-oriented UART input.
Inputs: text (required), port, baudrate, append_newline, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool has a clearly distinct purpose: connect/disconnect, flash, board info, state control, memory/register access, breakpoints, serial, symbol reading, and recovery. No overlap.
Most tools follow verb_noun pattern (e.g., flash_firmware, read_memory), with some simple verbs (connect, halt). 'unlock_recover' is slightly inconsistent, but overall patterns are clear.
20 tools for a debug probe server is reasonable. It covers core debug operations without being excessive, though some tools could potentially be combined.
The tool set covers all essential debug operations: connect, flash, state control, memory/register R/W, breakpoints, serial I/O, symbol reading, and recovery. Minor gaps like conditional breakpoints are acceptable.
Maintenance
Related MCP Connectors
Ovanek MCP: Model Context Protocol server for Ovanek platform tools; writes are dry-run by default.
MCP compatibility and transport verification server.
MCP compatibility and transport verification server.
MCP compatibility and transport verification server.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA basic MCP server implementation for testing purposes. Communicates via stdio and is designed to work with MCP-compliant clients.-
- AlicenseAqualityDmaintenanceStateful MCP server for driving debug probes (J-Link) to flash, debug, and inspect embedded targets. Enables AI agents to perform flash, memory, breakpoint, and ELF/SVD-aware operations conversationally.4187 PyPI11MIT
- FlicenseAqualityDmaintenanceA headless MCP server that enables AI tools (like Claude Code) to read and analyze serial logs from embedded boards (ESP32, STM32) for firmware debugging, with read-only tools for log retrieval and a built-in web viewer.61-
- FlicenseBqualityDmaintenanceMCP server for running shell commands on a Linux development board via UART serial.1-