MCP with RIG — connect your robot and external tools

Existing tools work through the configuration flow above. Expand this workshop only when you want to implement a new device function. The steps below involve firmware changes.

3. Prepare for the first custom tool

Before editing, complete one original build and flash for your actual robot. You should already have the ESP-IDF version from your model workshop installed (5.5.3 for TARS), the public source downloaded, the correct board and Overseas region selected, and the real serial port identified. If you have not done that yet, complete the setup in your Puppy, Hover, Arm or TARS workshop once, then return here.

TARS public source is available. Select RIG-Tars in the public board configuration. The TARS beginner workshop now covers its complete build, first edit, MCP tools and recovery. Use ESP-IDF 5.5.3 for that workshop; the repository documents TARS builds with this version.

Open the project root in your editor and use a local experiment branch. Preserve any existing edits. Choose the file for your actual model:

Find void InitializeTools(). Inside it, find the existing line auto& mcp_server = McpServer::GetInstance();. Place the example immediately after that line, keeping the original tools underneath. Add custom model tools here rather than editing the shared common-tool registrations.

4. Add the hello tool

If you already added self.robot.hello in the development workshop, keep that registration and skip to building/testing. Search before pasting: register each name only once.

mcp_server.AddTool(
    "self.robot.hello",
    "Run the hello test without moving the robot.",
    PropertyList(std::vector<Property>{}),
    [](const PropertyList&) -> ReturnValue {
        ESP_LOGI(TAG, "Hello tool called");
        return true;
    });

The code between the callback's braces does not run just because it was registered. It runs when the tool is called. Keep the surrounding braces, commas and final semicolon exactly as shown.

Save the file and run git diff in the project terminal. Check that your intended board file contains one new registration and that existing tools are intact. If other files already had edits, distinguish those from this experiment.

5. Build, flash and keep the log open

In the activated ESP-IDF terminal at the project root, first run:

idf.py build

Continue only after a successful build. Close an existing monitor with Ctrl + ]. Replace COM5 below with the port you previously identified:

idf.py -p COM5 flash monitor

Keep the robot supported and its moving parts clear: this tool adds no motion, but the existing startup behavior still runs. Wait for normal startup and network connection. To reopen the monitor without flashing, run idf.py -p COM5 monitor with your actual port.

Expected so far: the firmware starts normally. You do not need to see Hello tool called yet; no call has been made. A successful compile proves the code built, not that a client can invoke it.

6. Make a real call and verify it

Connect and refresh the tools

1. Power on the correct robot and confirm it is online in the international account you normally use. Confirm ordinary conversation works before diagnosing a custom tool.
2. After flashing, reconnect the existing robot conversation/client session so it can discover the updated tools. If your interface has a refresh-tools action, use it. Interface labels vary; this tutorial does not assume a hidden developer panel exists.
3. If a tool list is available, look for the exact name self.robot.hello. Tool discovery is different from invoking the tool: seeing its name means it was advertised, not that its callback ran.
4. If the client provides a tool inspector, select that name and use {} as the arguments. This means “no arguments.” Do not paste C++ or a shell command into the argument field.
5. Otherwise ask the connected assistant: “Call the self.robot.hello tool once and tell me its result.” Watch the serial log for Hello tool called. The client may not expose manual invocation; a voice request still depends on its tool support and selection.

Using a separate desktop AI client? Only proceed if your international service supplies a compatible MCP connection method for that client. Use its actual endpoint, transport and authentication instructions. The robot's Wi-Fi address, GitHub URL and serial-port name are not interchangeable MCP endpoints. If no compatible connection is provided, use the existing robot assistant and keep desktop-client setup as a separate task.

What success looks like: the callback message appears when you make the request and the tool returns success. In this firmware, a boolean result is represented as text in the MCP response; a client may display true rather than a spoken sentence. A friendly spoken reply alone does not prove a device tool was called.

Use one explicit request at a time. If a client retries, you may see more than one invocation; use its request activity and the log timing to investigate rather than assuming every spoken request always produces exactly one device call.

7. Optional: give a tool one input

Keep this section closed until hello works. It teaches argument handling without touching motors.

mcp_server.AddTool(
    "self.robot.double_number",
    "Double a whole number from 0 to 10 without moving hardware.",
    PropertyList({
        Property("number", kPropertyTypeInteger, 0, 10)
    }),
    [](const PropertyList& properties) -> ReturnValue {
        const int number = properties["number"].value<int>();
        const int result = number * 2;
        ESP_LOGI(TAG, "Double test: %d -> %d", number, result);
        return result;
    });

{"number": 3}

8. Let AI help with the smallest change

Open the actual project in your coding assistant. If it cannot read files, provide the relevant InitializeTools function and MCP type definitions. A repository URL alone does not guarantee file access. Choose one model in the prompt before submitting it.

I am a beginner using [RIG-Puppy / RIG-Hover / RIG-Arm].
Read my actual checkout of https://github.com/LuwuDynamics/rig_omni.
My original firmware already builds and runs with ESP-IDF 5.5.2 and Overseas configuration.
Inspect the model's InitializeTools function and main/mcp_server.h before editing.
Help me add self.robot.hello: no arguments, log "Hello tool called", return true, no movement.
If that name already exists, help me test it instead of registering it twice.
Explain the insertion point and each part in plain English. Show the smallest diff.
Keep existing tools, hardware settings, dependencies and account configuration unchanged.
Give the build command, manual flash/monitor steps, expected log/result and an undo step.
Do not flash, erase or invoke hardware tools automatically. Say which checks you actually ran.
If this checkout lacks support for my model, explain the missing support instead of inventing it.

Review the edited file, build it and observe the real call yourself. An AI message saying “the tool works” is not a substitute for the log and client result.

After hello succeeds, a good second request is: “Add a separate non-moving double_number tool accepting a required integer from 0 through 10. Verify the existing Property constructor, return the doubled value, and show valid, missing, wrong-type and out-of-range input tests.” Compare its proposal with the example above before applying it.

Something isn't working? Locate the failing step

Copy the first error and a small amount of surrounding output. Remove credentials before sharing. For AI-assisted diagnosis:

My model and source revision: [fill in].
Tool name: [exact name].
Build and flash outcome: [actual results].
Client tool list: [present / missing / no inspector available].
Arguments sent: [sanitized JSON].
Device log at invocation: [sanitized lines].
Client result or error: [sanitized output].
Find the failing stage: registration, discovery, invocation, argument validation, callback or return path.
Explain the smallest next check. Do not rewrite unrelated code or invent a server endpoint.

9. Keep your work or undo it

To undo hello, remove only its AddTool registration. If you tried double_number, remove its registration separately. Review git diff, build, flash the same model/region and refresh the tools. Confirm normal startup still works. Do not erase flash to remove a tool.

Your first milestone is complete when you can explain the tool name, arguments and result; observe the callback; and remove the change. Keep the working source/configuration and your test notes.

Reference when you need it

The examples follow the public RIG source, especially MCP types and tool results and registration and request handling. For the general host/client/server concepts, see the official MCP architecture guide. These are optional references; the first exercises are complete on this page.