Actions

Your miniapp can expose actions: typed, described capabilities that Mentra AI can call to drive it. You declare each action in miniapp.json and handle it in your background layer. Mentra AI reads your declarations and decides when to call them. Actions map 1:1 onto MCP tools (id to name, description, parameters to inputSchema), so the same declarations can be surfaced to external agents later.

Declare an action

List your actions in miniapp.json. The description is the contract Mentra AI reads, so say when the action should be used.

miniapp.json

{
  "actions": [
    {
      "id": "add_todo",
      "description": "Add an item to the user's todo list. Use when the user asks to remember, note, or add something.",
      "parameters": {
        "type": "object",
        "properties": {
          "text": { "type": "string", "description": "The todo item text" }
        },
        "required": ["text"]
      }
    }
  ]
}

Field	Rules
`id`	`^[a-z][a-z0-9_]*$`, unique within your miniapp, ≤64 chars.
`description`	Required, non-empty. The AI-facing contract: say when to use it.
`parameters`	A JSON-Schema object (the MCP subset): top-level `type: "object"`, `properties` typed `string` / `number` / `boolean` / `array` (of primitives), plus `enum`, `description`, `items`, and a top-level `required` array. Use `number`, not `integer`.

Handle it

background/index.ts

session.actions.handle("add_todo", async (params, ctx) => {
  // ctx.callerPackageName is host-stamped, so it's trustworthy.
  await todos.add(String(params.text));
  return { ok: true, count: todos.size };
});

One handler per id. Registering the same id twice throws.
A thrown handler rejects the caller, and your error message comes back to them.
The return value is serialized to the caller (max 256 KB).
handle returns a function that deregisters the handler.

How a call reaches you

When Mentra AI invokes one of your actions, the host headless-wakes your miniapp if it isn’t already running: it spawns your background context (no UI, no foreground change, so whatever the user is doing is undisturbed), waits for your handlers to register, delivers the call, and returns your handler’s result. Your miniapp keeps running afterward until it’s stopped. Because an inbound call waits only briefly for a just-woken miniapp to register, call session.actions.handle at the top of your registerMiniapp handler rather than after async setup.

Exposing actions with handle is open to every miniapp, so your miniapp is callable by Mentra AI today. The calling side (discovering, launching, and invoking other miniapps) is restricted to system miniapps. See System Miniapp APIs.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

Declare an action

Handle it

How a call reaches you

​Declare an action

​Handle it

​How a call reaches you

Declare an action

Handle it

How a call reaches you