Client Configuration

Environment Variables

All configuration is done via environment variables.

Variable	Description	Default	Example
SERIAL_PORT	Serial port — single device shorthand	—	/dev/ttyACM0, COM3
SERIAL_BAUD	Baud rate (used with SERIAL_PORT)	115200	9600
DEVICES	Multi-device config string	—	esp32:/dev/ttyACM0:115200

Priority: SERIAL_PORT → DEVICES

---

Configuration Formats

Single Device — SERIAL_PORT

SERIAL_PORT=/dev/ttyACM0 npx -y mcpu-client

Custom baud rate:

SERIAL_PORT=/dev/ttyACM0 SERIAL_BAUD=9600 npx -y mcpu-client

Multiple Devices — DEVICES

Format: id:port:baud (serial) or id:host:port:tcp (TCP), comma-separated.

Serial:

DEVICES=robot:/dev/ttyUSB0:115200,display:/dev/ttyACM0:115200 npx -y mcpu-client

TCP (WiFi):

DEVICES=robot:/dev/ttyUSB0:115200,sensor:192.168.1.50:3000:tcp npx -y mcpu-client

Virtual Mock Testing:

DEVICES=mock-mcu:mock npx -y mcpu-client

Windows:

set DEVICES=board1:COM3:115200,board2:COM4:115200 && npx -y mcpu-client

---

Memory Subsystem Configuration

MCP-U Client includes a built-in “Buffered Pull Memory” feature that stores sensor history and tool execution logs in a local SQLite database, allowing LLMs to query historical context securely. This feature is enabled by default.

Variable	Description	Default
MCPU_MEMORY_ENABLED	Enable memory subsystem	true
MCPU_MEMORY_CONNECTION_URL	SQLite connection path	sqlite:///./mcpu-memory.db
MCPU_SQL_READONLY_ENABLED	Expose sql_readonly_query tool	true
MCPU_BUFFER_DRAIN_ENABLED	Automated polling for buffered pins	true
MCPU_RAW_RETENTION_HOURS	Keep raw sensor samples for X hours	24
MCPU_TOOL_CALL_RETENTION_DAYS	Keep execution logs for X days	365

Configuration Examples

Via Command Line (CLI):

MCPU_RAW_RETENTION_HOURS=48 MCPU_BUFFER_DRAIN_ENABLED=false DEVICES=esp32:/dev/ttyUSB0:115200 npx -y mcpu-client

Via Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mcu": {
      "command": "npx",
      "args": ["-y", "mcpu-client"],
      "env": {
        "DEVICES": "mock-mcu:mock",
        "MCPU_MEMORY_ENABLED": "true",
        "MCPU_MEMORY_CONNECTION_URL": "sqlite:////absolute/path/to/my-memory.db",
        "MCPU_RAW_RETENTION_HOURS": "48"
      }
    }
  }
}

---

Device Format Specification

Format	Syntax	Example
Serial	id:port:baud	esp32:/dev/ttyUSB0:115200
TCP	id:host:port:tcp	sensor:192.168.1.50:3000:tcp

With multiple devices, tools are prefixed: robot__gpio_write, display__gpio_write

---

Dynamic Tool Discovery

The client has zero hardcoded tool names. On startup:

1. Connects to all configured devices
2. Calls get_info + list_tools on each
3. Converts firmware JSON Schema → Zod schemas at runtime
4. Registers one MCP tool per firmware tool
5. Auto-configures polling for any tool that declares McpPolling(ms) in firmware

Adding a new tool to firmware = the MCP tool appears automatically on next client restart.

Firmware-Driven Auto-Polling

When a tool is registered with McpPolling(interval_ms), the firmware includes "polling": {"enabled": true, "interval_ms": N} in its list_tools response. The client reads this and schedules periodic calls automatically — no env var required.

// Firmware — declare polling in the tool registration
mcp.add_tool("read_sensor", "Read sensor buffer", handle_sensor, McpPolling(2000));

The client starts polling read_sensor every 2 seconds on its own. If the result contains "type": "buffer" data, observations are written to the memory database.

---

Tool Naming

Scenario	Tool name format	Example
Single device	{tool_name}	gpio_write
Multi device	{device_id}__{tool_name}	robot__gpio_write

---

Supported OS

OS	Serial	TCP
Linux	✅ /dev/ttyUSB*, /dev/ttyACM*	✅
macOS	✅ /dev/tty.usbserial-*	✅
Windows	✅ COM3, COM4, …	✅

---

Finding Serial Port

OS	Command	Typical port
Linux	ls /dev/ttyUSB* /dev/ttyACM*	/dev/ttyACM0
macOS	ls /dev/tty.usbserial-*	/dev/tty.usbserial-*
Windows	Device Manager → Ports	COM3, COM4

Permission error on Linux:

sudo usermod -aG dialout $USER
# Log out and back in