esp32 mcp server: Giving AI Agents a Safe Handle on Hardware

An esp32 mcp server turns a five-dollar microcontroller into something an AI agent can discover and operate through the same Model Context Protocol that powers desktop tool calling. Instead of writing a custom REST API and then teaching every agent its quirks, you register tools like set_volume or read_sensor on the device, and any MCP-compatible backend can list them and call them over JSON-RPC 2.0. Espressif now ships an official MCP component in ESP-IoT-Solution, and the popular xiaozhi ESP32 voice assistant project has adopted MCP as its recommended IoT control protocol. This post walks through what exists today, how the two main approaches work, and the security decisions that matter before you let an agent touch real hardware. Source

What an esp32 mcp server actually is

Espressif's documentation describes an MCP component that provides a simplified API for common MCP functions, with support for HTTP and other transports. The supported chip list covers the parts most builders already have: ESP32, ESP32-C2, ESP32-C3, ESP32-C6 and ESP32-S3. The component ships with two reference examples that frame the two roles a device can play. The mcp_server example runs an MCP server on the ESP32 over HTTP, exposing JSON-RPC tools for device controls. The mcp_client example goes the other way, letting the ESP32 act as an MCP client that calls a remote MCP server. The API surface is grouped into three modules: Core and Manager for lifecycle, request dispatch and transport sessions; Tooling and Data for tool definition and execution; and Prompt, Resource and Completion providers. That structure mirrors the MCP specification itself, so anything you learn transfers to desktop MCP servers. Source

The official example, concretely

The mcp_server example in ESP-IoT-Solution is a good mental model for the whole pattern. It registers tools for device status queries, volume control with 0 to 100 range validation, screen brightness, light and dark theme switching, and HSV and RGB color control, plus resource registration, prompt rendering and a completion provider, all over full JSON-RPC 2.0 with built-in parameter validation and mutex-protected tool lists. After setting Wi-Fi credentials in menuconfig and flashing with idf.py, the serial log shows the server starting on port 80 with the endpoint /mcp_server. From there, a plain curl POST with a tools/list request returns every registered tool with its description and input schema, and a tools/call request invokes one by name. Two things worth noticing. First, the tool schemas travel with the device, so an agent does not need prior knowledge of your hardware: it discovers capabilities the same way it would from any MCP server. Second, the example runs plain HTTP on port 80, which is a lab setup, not a deployment posture. Source

The getting-started path, step by step

The example README lays out a build path that will be familiar to anyone who has flashed ESP-IDF firmware. Set the chip target with idf.py set-target, open menuconfig and enter your Wi-Fi SSID and password under the example connection configuration, then run idf.py -p PORT flash monitor. The serial output shows the device joining Wi-Fi, taking an IPv4 address, and logging that the MCP server started on port 80 with the /mcp_server endpoint registered. From that point the device is a working MCP peer, and the fastest first test is the curl tools/list call described above. For teams evaluating this for a product, the example also demonstrates the less glamorous parts that matter later: task-mode tool execution with polling for longer operations, thread-safe tool registration through mutex-protected lists, and parameter validation that rejects out-of-range values before they reach hardware. These are exactly the spots where a quick prototype quietly becomes an unsafe one, and the fact that Espressif models them in the example saves real debugging time. Source

The xiaozhi approach: MCP over WebSocket and MQTT

The xiaozhi-esp32 project, one of the most widely used open-source ESP32 AI assistants, documents MCP as its recommended protocol for IoT control. Its flow shows where this architecture leads in a real product: the device boots and connects to a backend over WebSocket or MQTT, the backend sends an initialize call to start the MCP session, then issues tools/list to discover the device's tools and their input schemas, and finally calls individual tools with tools/call. Tools are registered on the device through an McpServer singleton. Note the inversion compared with the Espressif example: instead of the device hosting an HTTP server that clients connect to, the device makes an outbound connection to a backend, and MCP rides on that persistent channel. For fleet deployments behind NATs and home routers, the outbound model is usually the practical one, because you avoid exposing a listening port on the device entirely. Source

Security: the part to get right before agents

Giving an agent a handle on physical hardware raises the stakes of every MCP security practice. The official example serves unauthenticated HTTP on port 80, which is fine on a bench and unacceptable on a real network: anyone on the LAN can list and call tools. The minimum posture for anything beyond a demo is to keep the endpoint on a trusted network segment, move to an authenticated and encrypted transport before exposing it further, and validate every parameter on the device, which the example's built-in range validation models well. Our MCP server security best practices post covers tool poisoning, over-broad tool descriptions and consent flows in detail, and all of it applies here, with the addition that a compromised tool call can flip a relay, not just leak data. Transport security patterns from our esp32 mqtt tls guide carry over directly, and if agents will trigger firmware updates, signed OTA as described in our esp32 ota update security post is the baseline. Source

Where this fits, in our assessment

This section is our read, separate from the sources. The interesting shift is not that an ESP32 can speak JSON-RPC; it is that the device side of IoT is converging on the same protocol as the agent side, which collapses the integration work between them. For builders, the practical guidance is straightforward. If you are prototyping, the Espressif mcp_server example is the fastest way to see an agent discover and drive hardware, and an afternoon of work. If you are building anything with a backend, study the xiaozhi flow, because outbound persistent connections are how real fleets stay reachable. And if you are adding voice, our esp32 ai voice agent build pairs naturally with MCP tool control, since the voice pipeline produces intents and MCP executes them. The constraint to respect is the one MCP cannot solve for you: the protocol standardizes how agents call tools, but the safety of what those tools can do, and who may call them, is still your engineering decision. Source