MCP Integration

Ameba-Claw supports the Model Context Protocol (MCP) through two independent CAP modules: cap_mcp_client lets the device act as an MCP client, connecting to external MCP Servers and bridging remote tools as local Capabilities; cap_mcp_server lets the device act as an MCP Server, exposing its own capabilities via the MCP protocol for external MCP clients (such as Claude Code) to call directly. The two directions are independent of each other, each with its own Kconfig option and can be enabled individually.

Module	Device Role	Typical Use Case
`cap_mcp_client`	MCP Client	Call MCP tools running on a PC, server, or other device
`cap_mcp_server`	MCP Server	Allow Claude Code, AI IDEs, and other tools to directly control the device

MCP Client

cap_mcp_client automatically connects to all external MCP Servers listed in vfs:/mcp/servers.json after the device comes online, and registers discovered remote tools as local Capabilities on the device. The LLM can call these tools directly, with no difference from calling built-in Capabilities.

Workflow

After the device successfully connects to Wi-Fi, cap_mcp_client automatically triggers the discovery process.
Reads vfs:/mcp/servers.json and connects to each server in turn.
Sends an initialize handshake request and a tools/list request to each server in sequence (MCP JSON-RPC 2.0 over HTTP POST).
Translates each returned tool into a claw_cap_descriptor_t descriptor (preserving the original tool name, description, and input schema).
Bulk-registers all tools for that server to the device Capability system, using mcp_<server_name> as the group_id.
The LLM can use these tools directly in subsequent conversations; when called, the device sends a tools/call request to the corresponding server and returns the result to the LLM.

Configuration File (servers.json)

The configuration file is located at vfs:/mcp/servers.json and can be edited via the Web admin panel under “MCP Management”, or modified directly in the file manager. If the file does not exist, a blank template will be created automatically on the device’s first boot.

Format example:

{
  "servers": [
    {
      "name": "my-tools",
      "url": "http://192.168.1.100:3000/mcp",
      "api_key": "",
      "use_bearer": false
    }
  ]
}

Field	Type	Description
`name`	string (required)	Server identifier. When registered in the Capability system, the group_id is `mcp_<name>`; also used as the display name in the Web admin interface.
`url`	string (required)	HTTP endpoint address of the MCP Server. The path is usually `/mcp`, e.g., `http://192.168.1.100:3000/mcp`
`api_key`	string (optional)	Authentication key. Leave empty to send requests without any authentication header.
`use_bearer`	bool (optional)	`true`: adds `Authorization: Bearer <api_key>` to the request header; `false` (default): sends the key as a custom header

Hot Reload (mcp_client_reload)

No device restart is required after modifying servers.json. Ask the AI to call the mcp_client_reload tool during a conversation, and the device will unload all old mcp_* cap groups and rediscover all servers. After the call, the connection result for each server (success/failure, number of tools discovered) is returned, which helps troubleshoot configuration issues.

It can also be triggered directly via an AT command:

AT+CLAW=cap,mcp_client_reload

Limitations

A maximum of 4 MCP Servers can be configured simultaneously, with a maximum of 8 tools discovered per server (32 tools in total).
Only HTTP MCP Servers are supported (JSON-RPC 2.0 over HTTP POST); stdio local processes and WebSocket transport are not supported.
Tool names retain their remote original names when registered, and can be referenced by tool name (AT+CLAW=cap,<tool_name>) or group_id (mcp_<name>).

Note

The build switch for cap_mcp_client is the Kconfig option CONFIG_CLAW_CAP_MCP_CLIENT, enabled by default.

MCP Server

cap_mcp_server registers a POST /mcp endpoint on the device HTTP Server, accepting JSON-RPC 2.0 requests from external MCP clients. External tools can call device capabilities directly via the standard MCP protocol without needing to understand any of Ameba-Claw’s internal interfaces.

Exposed Tools

The MCP Server exposes the following tools:

Tool Name	Description
`rtk_device_state`	Retrieves the current device state, including Wi-Fi information, heap memory usage, Agent running status, etc.
`rtk_router_trigger`	Sends an event to the device event router to trigger configured automation rules. Parameters: `event_type` (required), `text`, `target_channel`, `payload_json`
`lua_run` / `lua_run_async` / `lua_job_get`, etc.	Proxied from the device’s `lua` Capability group, allowing remote execution of Lua scripts and retrieval of results

Connecting to Claude Code

In the Claude Code configuration file (~/.claude.json, or %APPDATA%\Claude\claude.json on Windows), find the section corresponding to the current workspace and add the following mcpServers configuration (JSON format consistent with other MCP clients):

{
  "mcpServers": {
    "ameba-claw": {
      "type": "http",
      "url": "http://<device IP>/mcp"
    }
  }
}

Save the file and restart Claude Code to use device tools directly in conversations. The device IP address can be found on the Web admin homepage; Claude Code must be on the same local network as the board to access it.

Endpoint and Server Name

The default endpoint for the MCP Server is /mcp, and the server name (serverInfo.name) defaults to ameba-claw. Both values are specified at initialization via cap_mcp_server_config_t, with defaults defined in cap_mcp_server.h:

#define CAP_MCP_SERVER_DEFAULT_ENDPOINT  "/mcp"

/* Default config, equivalent to:
   { .endpoint = "/mcp", .server_name = "ameba-claw" } */
cap_mcp_server_init(&CAP_MCP_SERVER_DEFAULT_CONFIG);

Note

The build switch for cap_mcp_server is the Kconfig option CONFIG_CLAW_CAP_MCP_SERVER, enabled by default.

Warning

The /mcp endpoint requires no authentication by default; any client that can reach the device’s HTTP port can invoke device capabilities. The lua_run tool allows execution of arbitrary Lua code, so be sure to verify the trustworthiness of the connecting party. If the device is on an untrusted network, it is recommended to place it on an internal network and avoid exposing the HTTP port externally.