For years, the workflow for adding a new capability to a robot or an AI agent has remained frustratingly static. When a developer wants a robot to perform a new task—perhaps checking the current stock price or fetching a weather report—the process typically involves diving into the source code, modifying the core logic, and triggering a full system redeployment. This cycle creates a significant operational bottleneck where the speed of innovation is limited by the stability of the deployment pipeline. The friction between wanting a new feature and actually seeing it execute on physical hardware has long been the Achilles' heel of embodied AI development.
The Architecture of MCP-Driven Tool Integration
Reachy Mini addresses this bottleneck by implementing the Model Context Protocol (MCP), a framework that allows the robot to integrate remote tools hosted on Gradio Spaces through simple profile configurations. Instead of hard-coding API calls into the robot's brain, developers can now inject new capabilities using a single command line interface.
python main.py add <space_name>When this command is executed, the system performs a multi-step validation process. It first verifies the validity of the specified Gradio Space on the hub and then probes the MCP endpoints to discover a list of available tools. Once the discovery phase is complete, the unique IDs of these tools are automatically appended to a `tools.txt` file within the active profile. If no specific `REACHY_MINI_CUSTOM_PROFILE` is defined, the system defaults to the base profile for storage. To validate this pipeline, the developers introduced two canary tools: a web search function and a weather retrieval tool. The underlying LLM reads the name and a brief description of each tool and autonomously decides which one to invoke based on the conversational context.
Management of these tools is handled through a dual-file system consisting of `instructions.txt`, which houses the system prompts, and `tools.txt`, which acts as a strict gatekeeper. If a tool's ID is not explicitly listed in `tools.txt`, the model is incapable of recognizing or calling it. To prevent naming collisions between local and remote tools, Reachy Mini employs a namespace strategy using double underscores (`__`). Any hyphens, dots, or slashes found in the Gradio Space slug are converted into underscores to create a local alias, ensuring that tools from multiple different Spaces can coexist within a single profile without conflict.
System stability is further reinforced by a fail-fast strategy at the registry level. The system checks for the uniqueness of the `Tool.name` value; if two tools from different sources share the same name, the application terminates immediately to prevent unpredictable behavior. While the system attempts to keep IDs concise by removing unnecessary Space name prefixes, it will retain the full namespace if a collision is detected. All installation metadata is stored permanently at `~/.reachy_mini/installed_spaces` to ensure persistence across sessions.
Decoupling Hardware Control from Information Retrieval
The true shift in Reachy Mini's design is the absolute separation of concerns between local hardware control and remote information acquisition. This creates a tiered execution environment where tools are categorized by their risk profile and latency requirements.
Local tools are reserved for direct hardware manipulation. Functions such as `move_head` for physical orientation or `play_emotion` for facial expressions are implemented as Python files located within the profile folder or the `external_tools/` directory. Because hardware control involves physical risks—such as collisions—and requires near-instantaneous response times, these tools are deployed internally and executed within the local network to minimize latency.
Remote tools, conversely, handle all data-heavy or external-facing tasks like web searching or weather updates. These are hosted on external Gradio Spaces and are designed to be stateless, meaning they do not store session data between calls. This architecture allows developers to leverage complex cloud-based API logic and heavy library dependencies without bloating the robot's onboard firmware. By moving these dependencies to the cloud, the update cycle for a robot's knowledge base is completely decoupled from the update cycle of its physical firmware.
This strategy establishes a Trusted Core—a minimal, stable set of internal instructions—while pushing volatile, ever-changing features to the periphery. Developers can test, replace, or update a web search tool in the cloud and have the robot adopt the change instantly without risking a bricked device or a failed firmware flash. To handle the inherent latency of network calls, Reachy Mini uses prompt-based orchestration. The system is instructed via the prompt to invoke tools in parallel when possible, preventing the robot from freezing while waiting for sequential API responses. However, the developers have maintained a clear boundary: if a task requires deterministic, strict sequencing, that logic is moved out of the probabilistic prompt and into the hard-coded Python logic.
This modular ecosystem transforms the role of the robot developer. To contribute a new capability, an external developer simply needs to publish a public Gradio Space with a standard MCP endpoint and tag it with `reachy-mini-tool` and `mcp`. The robot's ability to interact with the world is no longer a reflection of how much code is written into its core, but rather how effectively an orchestrator can combine these modular tools.
When a robot can search the web for a fact and simultaneously nod its head using a local tool, it bridges the gap between digital intelligence and physical presence. The evolution of Reachy Mini suggests that the future of embodied AI lies not in monolithic software updates, but in the fluid orchestration of a global API ecosystem.
