MCP User Guide

Overview

MCP (Model Context Protocol) is an open standard protocol introduced by Anthropic that lets AI Agents securely connect to external tools, data sources, and workflows. Through MCP, AI Agents move beyond suggestions — they can directly perform actions. Claude Code, Cline, Continue, Roo Code, and other mainstream AI Agents are all supported.

Ameba provides two MCP services with distinct roles. Together they form an automated iteration loop: query docs → modify code → build → flash → observe behavior:

• Documentation Query MCP (knowledge layer) — a cloud-hosted MCP server that lets AI Agents query the Ameba official documentation over HTTP to learn API usage and example code.

• SDK Development MCP (execution layer) — a local MCP server, launched directly on the developer’s machine by the AI client (Claude Code) and communicating over standard input/output without networking or extra authentication. It can directly modify project configuration, build, flash, and verify code execution.

The Documentation Query MCP shares its knowledge source with the AI Chatbot, but they serve different use cases: the chatbot is for developers asking questions manually; the Documentation Query MCP is for AI Agents that automatically query documentation in real time during SDK development to support code-level decisions — that is its core value.

The diagram below shows how the dev board, PC, AI Agent, both MCP services, and the Ameba SDK relate to one another, along with a typical development workflow:

1. Edit code: the Agent modifies SDK source files in the editor, guided by both the actual SDK code and the Documentation MCP knowledge;

2. Build firmware: the Agent calls the build_firmware tool to trigger cmake/ninja compilation, and automatically syncs the flash layout configuration to project_info.json5;

3. Flash firmware: the Agent calls the flash_firmware_tool tool to write firmware to the dev board via AmebaFlash.py;

4. Serial verification: the Agent calls serial_expect_tool and related tools to wait for boot logs or run interactive commands and verify the result.

Documentation Query MCP

The Ameba AIoT documentation provides an MCP server that shares its knowledge source with the AI Chatbot. After installing the Ameba Documentation Query MCP server, AI Agents can directly query and retrieve content from the Ameba AIoT official documentation.

Getting the MCP Server URL

Steps to obtain the MCP server URL:

1. Open the RealMCU AIOT website

2. Click the AI icon in the lower-right corner to open the RealMCU AI Chatbot

3. In the dialog, find the Use MCP dropdown

4. For Claude Code, click Add to Claude Code and copy the CLI command

5. For other AI Agents (Roo Code, Cline, Continue, etc.), click Copy MCP Link to get the MCP server URL

Note

MCP server URL:

https://ameba-aiot.mcp.kapa.ai

After obtaining the MCP server URL, follow the tab below for your AI Agent to complete the setup.

Installation and Authentication

General steps: 1) get the MCP service URL (see previous section); 2) configure the MCP client; 3) complete authentication (typically via GitHub OAuth); 4) start using it.

Claude CodeClineRoo CodeContinue

Claude Code:

Step 1: Add the MCP service

Run the following command in your terminal to add the Ameba Documentation Query MCP service to Claude Code:

claude mcp add --transport http realmcu-ask-ai-docs https://ameba-aiot.mcp.kapa.ai

Parameters:

• --transport http : use HTTP transport

• realmcu-ask-ai-docs : MCP server name (customizable)

• https://ameba-aiot.mcp.kapa.ai : MCP service URL

Step 2: Complete authentication

1. Open Claude Code

2. Type the /mcp command in the dialog and check the realmcu-ask-ai-docs authentication status:

   realmcu-ask-ai-docs · △ needs authentication
   

3. Press Enter to confirm authentication, then follow Claude’s prompts to complete the flow

4. Once authenticated, return to the Claude interface and continue the conversation

5. Type /mcp again to verify the status

   realmcu-ask-ai-docs · ✔ connected
   

Tip

• List installed MCP services: claude mcp list

• Remove the MCP service: claude mcp remove realmcu-ask-ai-docs

Query Examples

Examples of querying Ameba documentation, using Claude Code:

Example 1: query the OTA compression feature overview

Example 2: query GPIO usage

MCP Features

The Documentation Query MCP server uses HTTP and exposes the following tool to AI Agents:

Tool	Description
search_realtek_knowledge_sources(query)	Performs semantic search across Realtek’s documentation and other knowledge sources, returning the most relevant text fragments and source links — providing AI Agents with official reference material.

Troubleshooting

Symptom / Question	Resolution
MCP service connection fails	Verify the network can reach ameba-aiot.mcp.kapa.ai ; verify the authentication Token is correct
How long does authentication remain valid	The validity depends on the Token type and is usually long-lived. To re-authenticate, tell the AI Agent “re-authenticate the MCP service”
Can multiple MCP services be configured at once	Yes. Add multiple MCP server entries in the same configuration file using distinct server names
The AI Agent does not call the MCP service on its own	The current conversation context did not trigger an invocation. Tell the AI explicitly to query via MCP, e.g., “query Ameba’s OTA feature via the realmcu-ask-ai-docs MCP service”

SDK Development MCP

The SDK Development MCP launches its MCP server as a local subprocess and communicates with the AI client over standard input/output, requiring no network connection or additional authentication. The AI can directly modify project configuration, build, flash, and read/write the serial port — driving an automated, closed-loop development workflow based on the returned results.

This MCP is deeply optimized for embedded development: tool composition, parameter design, and return-value structure are all designed with agent usability as the top priority. Build and flash logs are specially compacted — compared to running CLI commands directly, they consume far less context while preserving critical error information and rich hints that help the agent accurately determine its next action.

Environment Setup and Registration

Step 1: Initialize the environment and install dependencies

Linux / macOS / WSL2Windows

Linux / macOS / WSL2:

Replace <SDK_ROOT> with the actual absolute path of the SDK (e.g. /home/user/ameba-sdk). Run the following from the SDK root to initialize the Python virtual environment and toolchain, and complete the first build:

cd <SDK_ROOT>
source env.sh
ameba.py build

Step 2: Register the MCP

Register the SDK Development MCP with the AI client. The configuration applies to the current SDK workspace; different SDK checkouts do not interfere with each other.

Claude CodeTraeCline

Claude Code:

Run the registration command from the SDK root (written to the workspace scope of ~/.claude.json or %APPDATA%\Claude\claude.json):

# Linux / macOS / WSL2
claude mcp add ameba-dev -- <SDK_ROOT>/tools/ameba/ameba_dev_mcp/launcher.sh

# Windows
claude mcp add ameba-dev -- <SDK_ROOT>\tools\ameba\ameba_dev_mcp\launcher.bat

Verify:

claude mcp list
# Expected: ameba-dev: ✓ Connected

Uninstall:

claude mcp remove ameba-dev

Note

The MCP server requires .venv to exist before it can start. If .venv has not been created when registering the MCP server, the AI client will show a connection failure. Complete Step 1 first, then restart the AI client to connect automatically.

Board Configuration

Before first use, run the following in the Claude Code chat:

/ameba-setup-boards

The AI will guide you through entering the board model, serial port, and other information, and automatically perform a read-only environment check — no manual JSON editing required. After setup, two configuration files are generated in the SDK root:

File	Description
board_info.json5	Board configuration: alias → SoC model + serial port + connection type (local/remote)
project_info.json5	Flash layout: firmware files and address table per SoC, auto-populated after the first build_firmware

To add or remove boards or change ports later, re-run /ameba-setup-boards or edit board_info.json5 directly. To manually specify the .bin files and flash addresses, see Appendix: project_info.json5 manual mode.

Typical Agent Workflow

Tell the AI your development goal in Claude Code, and it will sequentially call build_firmware → flash_firmware_tool → serial_connect_tool → serial_expect_tool → serial_disconnect_tool to complete one full verification cycle:

# Tell the AI in Claude Code:
Update the log print in main() to include the project version number. Build and flash to RTL8720E_COM20, then show me the boot log once it comes up.

Example AI tool call sequence:

build_firmware(alias="RTL8720E_COM20")
flash_firmware_tool(alias="RTL8720E_COM20")
serial_connect_tool(alias="RTL8720E_COM20")
serial_expect_tool(alias="RTL8720E_COM20",
                   patterns=["KM4 START SCHEDULER", "Crash Dump"],
                   timeout=20.0)
serial_disconnect_tool(alias="RTL8720E_COM20")

MCP Features

The SDK Development MCP exposes three categories of functionality to the AI Agent:

• Tools are operations the AI can invoke directly (e.g. build, flash, serial read/write);

• Prompts are pre-defined guided workflows the agent follows to complete multi-step interactive tasks;

• Resources are read-only data the AI can retrieve (e.g. device profiles, configuration files).

Tools

Tool	Description
set_target	Switch the current build target SoC
build_firmware	Build firmware for the current SoC; automatically syncs project_info.json5 on success
flash_firmware_tool	Flash firmware to the dev board using board/project configuration
list_serial_ports_tool	List available serial ports on the local machine or for a specified board
scan_remote_ports_tool	Scan available serial ports on a remote AmebaRemoteService (no board_info.json5 required)
apply_board_config_tool	Write or merge board entries into board_info.json5
env_pre_check_tool	Read-only environment check: validates JSON configuration, serial port visibility, and remote TCP connectivity
kconfig_get	Read the current value of one or more Kconfig symbols
kconfig_set	Set Kconfig symbol values and regenerate per-core headers
kconfig_search	Search Kconfig symbols by name or prompt text (regex supported)
serial_connect_tool	Open the serial port; resets the board and clears the buffer by default
serial_disconnect_tool	Close the serial connection and release the port
serial_command_tool	Send a command and wait for a response (buffer drain + write + pattern match)
serial_expect_tool	Block until a specified pattern matches, idle timeout, or hard timeout fires
serial_read_tool	Non-blocking snapshot of the current receive buffer

Prompts

Prompt	Description
/ameba-setup-boards	Guides board configuration initialization in one interactive session, generates board_info.json5, and automatically calls env_pre_check_tool to verify the setup

Resources

Resource URI	Description
device://profiles	List all supported device profiles and memory types
device://{device_name}/info	Get detailed information for a specific device: flash layout, RAM address, firmware image list, etc.
device://{device_name}/{memory_type}/info	Get the detailed profile for a specific device and memory type (nor/nand)
board://list	List all configured board aliases in board_info.json5
board://{alias}	Get the resolved configuration for a single board (passwords masked)
config://project_info	Full project_info.json5 contents (flash layout)
config://board_info	Full board_info.json5 contents (passwords masked)
debug://hardware	Hardware troubleshooting reference (drivers, auto-download circuit, common error codes)

Troubleshooting

Press Ctrl+O in Claude Code to expand the detailed parameters and return values of MCP tool calls and inspect specific error codes. Notes:

• Remote scenario: when the dev board is connected to a Windows PC, run AmebaRemoteService.exe on that PC to forward the serial port over TCP (port 58916).

• Auto-download circuit: the dev board must support the hardware auto-download circuit; otherwise automatic download and automatic reset will not work. (For auto-download circuit requirements, see <SDK_ROOT>/tools/ameba/ameba_dev_mcp/hardware_debug.md.)

Symptom / Error code	Resolution
BOARD_CONFIG_MISSING / PROJECT_CONFIG_MISSING	Re-run /ameba-setup-boards to generate the configuration files, or manually fill in the fields using the template_path in the error envelope
PORT_NOT_VISIBLE	Make sure the dev board is plugged in
REMOTE_UNREACHABLE	Start AmebaRemoteService.exe on the remote Windows PC and check that port 58916 is not blocked by a firewall
RESET_FAILED or flash stalls entering download mode	Meet the hardware auto-download circuit requirements described in <SDK_ROOT>/tools/ameba/ameba_dev_mcp/hardware_debug.md
ALIAS_REQUIRED / ALIAS_NOT_FOUND	The error message lists the available aliases; retry with the correct board alias
ameba-dev shows as disconnected in claude mcp list	Confirm that source env.sh has been run and the initial build completed, then restart Claude Code. Make sure <SDK_ROOT> in the registration command is a valid absolute path
Server fails to start (import error)	Run <SDK_ROOT>/tools/ameba/ameba_dev_mcp/launcher.sh (launcher.bat on Windows) manually to view the full stderr output

Appendix: project_info.json5 Manual Mode

Each SoC entry in project_info.json5 supports two modes:

Mode	Who manages images	Will build_firmware overwrite the images field?
auto	MCP writes automatically	Yes (updated automatically after every successful build)
manual	User fills in by hand	No (MCP never modifies this entry)

Manual mode is suitable for the following scenarios:

• Need to flash a fixed .bin to a specific address without letting build results overwrite the configuration;

• Decoupling flashing from compilation (e.g., flashing a pre-built release bin);

• Need to customize which images participate in flashing (add/remove entries).

Configuration

Set flash_layout_setting_mode to "manual" and fill in build_dir and images[] manually:

"RTL8721F": {
  "flash_layout_setting_mode": "manual",
  "build_dir": "/home/me/sdk/build_RTL8721F",
  "memory_type": "nor",
  "images": [
    {
      "path": "/home/me/sdk/build_RTL8721F/boot.bin",
      "start_addr": "0x08000000",
      "end_addr": "0x0803FFFF"
    },
    {
      "path": "/home/me/sdk/build_RTL8721F/app.bin",
      "start_addr": "0x08040000"
      /* end_addr is optional; if omitted, it is inferred from the actual file size and used for region overlap checking */
    },
    {
      /* optional=true: missing files only produce a warning, not a flash failure */
      "path": "/home/me/sdk/build_RTL8721F/vfs.bin",
      "start_addr": "0x083C0000",
      "optional": true
    }
  ]
}

Field reference:

Field	Required	Description
flash_layout_setting_mode	Yes	Fixed to "manual"
build_dir	Yes	Absolute path to the build_<SOC>/ directory
memory_type	No	"nor" / "nand" / "ram" ; defaults to defaults.memory_type
images[].path	Yes	Absolute path of the .bin file
images[].start_addr	Yes	Flash start address, format 0x...
images[].end_addr	No	End address (inclusive); if omitted, inferred from file size, used only for region overlap checking
images[].optional	No	When true , a missing file produces a warning instead of an error (suitable for optional images such as VFS)

Migrating from auto to manual

1. Locate the SoC’s auto entry in the current project_info.json5 and copy out the images data inside the generated by build comment block;

2. Change flash_layout_setting_mode to "manual" ;

3. Remove the /* === generated by build, do not edit === */ comment;

4. Adjust images[] as needed.

After this, a successful build_firmware will not overwrite this entry — the flash addresses are entirely under your control.

Notes

• All paths must be absolute; relative paths are rejected by validation;

• images[] must contain at least one entry, otherwise MANUAL_IMAGES_EMPTY is reported;

• Before flashing, MCP performs region overlap checking (when end_addr is known);

• In manual mode, MCP does not re-parse the SDK flash layout; the user is responsible for keeping addresses consistent with the SDK.