MCP server

espx mcp serves the Model Context Protocol on stdio. A coding agent connected to it can create a project, build it, flash the board on your desk, read the boot log and fix what it sees, with nothing but espx. The agent works in a loop: build, flash (or run, which also watches the boot log), read the monitor, fix, repeat.

Add espx to a client

Run espx mcp install once per client:

espx mcp install --client claude-code     # prints: claude mcp add espx -- /path/to/espx mcp
espx mcp install --client codex           # prints: codex mcp add espx -- /path/to/espx mcp
espx mcp install --client cursor          # writes ~/.cursor/mcp.json
espx mcp install --client vscode          # writes .vscode/mcp.json in this directory
espx mcp install --client claude-desktop  # writes Claude Desktop's claude_desktop_config.json

For the JSON files espx merges in its own entry and keeps every other key. --print shows the config instead of writing it. Restart the client afterwards so it loads espx. The entry starts the espx binary you ran install with:

{
  "mcpServers": {
    "espx": { "command": "/home/you/.cargo/bin/espx", "args": ["mcp"] }
  }
}

The desktop app does the same for your whole user account, with Connect and Disconnect buttons per client.

Let the agent touch a board

An agent may flash, reset or erase only a board the project allows in espx.toml. By default that is the project's bound board, [board] id, and erasing is off. Create projects with a binding:

espx new blinky --board-id 58:8C:81:53:AD:2C

An agent does the same with project_new and board_id. A call outside the policy fails with policy_denied, and the message says which key to set. Commands you run yourself are never checked. Agent policy covers the [agent] table and the audit log.

Tools

espx serves 22 tools. Every tool carries readOnlyHint and destructiveHint annotations, and every result is a one-paragraph summary plus structured data.

Most tools take dir, the project directory. It defaults to the directory espx mcp was started in, and relative paths resolve against it. Board tools take port: a serial port, a board id from devices, or a name from espx boards name. Leave it out when the project binds a board, pins a port in espflash_ports.toml, or exactly one board is attached.

Every call's arguments are checked strictly; an unknown argument is an error. A bad argument, a failed build or an espx error comes back as a tool result with isError: true, never as a JSON-RPC error, so the agent reads it. When an error caused it, the structured content holds error with a stable code (invalid_arguments for bad arguments) and a message that says what to do next. The codes are listed in Exit codes.

Builds

build (and the build step of flash and run) returns each compiler message as a diagnostic with its level, code, file, line and column. A failed build names the first error and its location in the summary, with rustc's rendered text as the body. A successful one reports the image size against the app partition, and an image that does not fit fails before anything reaches the board.

Monitoring

run and monitor_start open a monitor session, which espx reads itself: it decodes defmt and resolves panics against the project's release binary. monitor_start resets the board when the port opens, so the log starts at boot; pass reset: false to join without resetting. Pass replay with the path of an espx monitor --record file to play a recording through the same tools.

monitor_read arguments:

The result is shaped for a model to read. Runs of identical lines collapse into one with ×N. Each boot shows its reason and the ROM's rst: line. Every panic or exception frame inside the project carries seven numbered source lines, the frame's line marked with >. The summary lists the boots and says so when the last one was a watchdog reset, a panic or a brownout, or when the same reason repeats, which is a reset loop.

run takes until, expect, reject and timeout_s: how long to watch after flashing, 30 seconds when there are patterns to match, else 5 seconds of boot log. A run that hits a rejected pattern, or whose expectations did not all match, is an error result. The session stays open for monitor_read.

After a flash or reset with a session open, the tool waits up to 3 seconds for the new boot and names its reason.

Jobs

setup, build, flash, erase and run can take longer than a client wants to wait. Each takes wait_s (default 25). If the work is done in time the call returns its result. Otherwise it returns {job, state: "running", tail, progress} and keeps going:

• job_status returns the state (running, done, failed or cancelled), progress and the last output lines.
• job_wait waits up to its own wait_s and returns the same result the original call would have, or running again.
• job_cancel stops the job.

Cancelling the starting call, or a job_wait, through MCP's notifications/cancelled cancels the job too. A cancelled build is killed with its whole process group. A flash cannot stop in the middle of a write, so a cancelled flash stops after it. A cancelled setup finishes its current download in the background.

When the request carries a progressToken, every step goes out as notifications/progress: cargo's Compiling lines, each block a flash writes, each setup step. Jobs live in memory, the newest 64, so restarting the server forgets them.

When the agent needs a person

When espx cannot get the bootloader to answer, also after one retry at 115200 baud, or the board is not on the USB bus, the result carries needs_human with an action and a message:

Nothing else asks for a person. The server's own instructions tell the agent to ask for help only when a result carries needs_human. The desktop app reads it from the audit log and shows a banner.

Resources

Prompts

Sharing boards

espx mcp uses the same board hub as the CLI and the desktop app. When nothing else serves it, espx mcp serves it on ~/.espx/hub.sock, so two agents, or an agent and a terminal, share one board. Every flash, reset, erase and board-info read is leased under the client's name, espx mcp (claude-code) for example, and another holder's call fails with board_leased until it is done. If the process serving the hub quits, the server reconnects or opens the boards itself.

Every tool call is appended to ~/.espx/agent.log. espx log prints it; see Agent policy.

Related

• Agent policy
• Agent context
• Monitor and replay