Skip to main content

MCP: Mobium as an agent's tools

mobium mcp serves every one of Mobium's tools over the Model Context Protocol, on stdio, so an agent — Claude Code, or any MCP client — drives devices with the same tools the command line and the language clients use. This guide is how to connect one, what it sees, and how its answers and failures come back.

Everything below is what ran on 2026-09-28 against MobiumApp on an Android 15 emulator: a Claude Code agent given only Mobium's tools, and the raw protocol, as an MCP client speaks it. Long answers are trimmed where they say so. The full tool list is generated: API.md.

1. Connect it​

In Claude Code:

claude mcp add mobium -- mobium mcp

With more than one device, pin one — mobium mcp --device emulator-5554 — or let the agent pass device to each call. --driver wda makes iOS the default.

Other MCP clients take the same server in their JSON configuration, under mcpServers:

{
"mcpServers": {
"mobium": {
"command": "mobium",
"args": ["mcp", "--device", "emulator-5554"]
}
}
}

That is the shape the run below used, passed to Claude Code as --mcp-config; where each client keeps the file is the client's own documentation. command needs mobium's full path if it is not on the PATH the client starts with.

2. An agent at work​

Claude Code, non-interactively, with Mobium's server and nothing else allowed:

claude -p "Use the mobium tools. On the Android emulator, open the app
dev.mobium.mobiumapp, go to its Login Demo, sign in with username mobium and
password wrongpass1, and tell me exactly what the app says. Keep it short." \
--mcp-config mobium.json --strict-mcp-config --allowedTools mcp__mobium

The calls it made, in order, each with the structured half of its answer (trimmed to a line):

app_launch {"app": "dev.mobium.mobiumapp"}
→ {"app":"dev.mobium.mobiumapp","device":"emulator-5554"}
app_tap {"target": "text=Login Demo"}
→ {"action":"tap","target":"text=Login Demo","x":540,"y":677}
app_find {"locator": "role=input"}
→ {"elements":[{"ref":"@e3","label":"username","role":"input", …
app_fill {"target": "testid=username", "text": "mobium"}
app_fill {"target": "testid=password", "text": "wrongpass1"}
app_find {"locator": "role=button"}
→ {"elements":[{"ref":"@e2","label":"Back","role":"button", …
app_tap {"target": "testid=loginBtn"}
app_text {}
app_wait_for {"target": "text=Signing in…", "condition": "hidden"}
→ {"target":"text=Signing in…","condition":"hidden","waited_ms":15}
app_text {}

And its answer, in 12 turns and 23 seconds:

The sign-in failed. The app says:

"Incorrect username or password."

Before that, both fields passed their checks: "✓ Username looks good." and "✓ Password meets the requirements." The screen lists the demo account's correct password as hunter2.

What the agent left on screen: the Login Demo showing "Incorrect username or password."

It found the fields by role, used the locators the answers gave it, saw "Signing in…" and waited for it to go rather than guessing a delay, and never saw the password it typed: a password field is never read back as text.

3. What a client sees​

The handshake, as sent and answered:

>>> {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "probe", "version": "1"}}}
<<< {
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {
"tools": {}
},
"serverInfo": {
"name": "mobium",
"version": "0.1.0-dev"
}
}
}

tools/list answered with 71 tools, 19 of them marked read-only (on 2026-10-24 it answers 75, still 19 read-only). One, with its description cut short and its schema reduced to the argument names:

{
"name": "app_tap",
"description": "Tap an element. Give a ref from app_map (\"@e5\"), a locator (\"text=Sign In\", \"testid=submit\", \"label=Email\", \"role=button\"), or x and y in device pixels. The ele …",
"inputSchema": {
"type": "object",
"properties": [
"device",
"double",
"driver",
"fingers",
"target",
"x",
"y"
]
},
"annotations": {
"readOnlyHint": false
}
}

Every schema says additionalProperties: false, so an argument a tool does not take is refused rather than ignored. readOnlyHint is on every tool: true for the 22 that only read — app_map, app_text, app_state and the like — and false for everything that can change the device; tools that act also say destructiveHint and idempotentHint where they can (section 7).

68 of the 78 tools also carry an outputSchema: the shape of the structuredContent every successful call returns, so a client can check what it is handed. It is generated from the code by Go's type checker (internal/apisurface/outputschema, run by make api), and only for a tool that always answers with one type; the other ten, such as app_screenshot, app_batch and app_logs, answer with an image or with one of several shapes, and carry none. A test holds every schema to empty and filled values of its type, and make ci fails when one is out of date.

4. Answers: text, data and images​

Every answer has two halves: content, text for the model to read, and structuredContent, the same answer as data for code:

>>> {"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "app_map", "arguments": {}}}
<<< {
"jsonrpc": "2.0",
"id": 4,
"result": {
"content": [
{
"type": "text",
"text": "@e1 homeList (list)\n@e2 WebViews (button)\n@e3 Login Demo (button)\n@e4 OTP Demo (button)\n@e5 Location Demo (button)\n@e6 Pager Demo (button)\n@e7 Interruption Demo (button)\n@e8 Form Demo (button)\n@e9 Gestures (button)\n@e10 Motion Demo (button)\n@e11 Crash Demo (button)\n@e12 Storage Demo (button)\n@e13 Dialog Demo (button)"
}
],
"structuredContent": {
"elements": [
{
"ref": "@e1",
"label": "homeList",
"role": "list",
"locator": {
"kind": "testid",
"value": "homeList",
"exact": true
},
"bounds": {
"x1": 0,
"y1": 136,
"x2": 1080,
"y2": 2400
}
},
{
"ref": "@e2",
"label": "WebViews",
"role": "button",
"locator": {
"kind": "testid",
"value": "webviewhubBtn",
"exact": true
},
"bounds": {
"x1": 42,
"y1": 592,
"x2": 1038,
"y2": 723
}
},
"… 11 more"
],
"context": "NATIVE_APP",
"device": "emulator-5554"
}
}
}

(Trimmed to two of the thirteen elements.) A screenshot with no path comes back as an image the model can look at:

>>> {"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "app_screenshot", "arguments": {}}}
<<< {
"jsonrpc": "2.0",
"id": 6,
"result": {
"content": [
{
"type": "image",
"data": "iVBORw0KGgoAAAANSUhEUgAA… (179688 base64 characters)",
"mimeType": "image/png"
}
]
}
}

5. Failures​

A tool that fails answers with isError: true — never a protocol error, which is kept for a malformed request — and the failure as data: a code, the message, a remedy that works, and whether retrying could help:

>>> {"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "app_tap", "arguments": {"target": "testid=noSuchButton"}}}
<<< {
"jsonrpc": "2.0",
"id": 5,
"result": {
"content": [
{
"type": "text",
"text": "no element matches testid=noSuchButton on the current screen — the screen may have changed, run app_map again"
}
],
"structuredContent": {
"code": "no_such_element",
"message": "no element matches testid=noSuchButton on the current screen — the screen may have changed, run app_map again",
"remedy": "run app_map again, or app_scroll_to if it may be off screen",
"retryable": false,
"details": {
"locator": "testid=noSuchButton"
}
},
"isError": true
}
}

The codes are the same everywhere — the command line's exit status, every client's exceptions — and listed in the CLI guide. An agent should decide by code, and read remedy for what to do next.

6. Sessions, and sharing a device​

mobium mcp runs the tools in its own process: the editor's MCP connection is the long-lived thing, and it holds its own device sessions, with the agent's refs. The command line and the language clients share a daemon instead. A device's automation server holds one session at a time, so an agent's MCP server and a mobium command driving the same device at the same time take it from each other — each recovers, but neither is reliable. Give each a device, or take turns.

Everything an agent changes for a session — network conditions, accessibility settings — is put back when the session ends: an app_session with action: "end", or the server's exit when the client disconnects.

7. Limiting what an agent can do​

Two limits, set by whoever starts Mobium and never by a call, so the agent cannot lift them:

claude mcp add mobium -- mobium mcp --read-only # look, never act
claude mcp add mobium -- mobium mcp --apps dev.mobium.shop # act only in this app

--read-only refuses every call that acts, and tools/list offers only the tools that can read, 36 of the 78. A tool that reads unless told to act, such as app_alert, is offered and refuses only the acting form:

app_tap acts, and this Mobium allows only reading (MOBIUM_READ_ONLY, or mobium mcp --read-only)
next: read the screen with app_map, app_text or app_screenshot; acting needs Mobium started without the read-only setting, which only whoever starts it can change

--apps, a comma-separated list, is the only apps a call may name (app_launch, app_clear_data, …) and the only apps an action on the screen may act on: a tap with another app in front is refused, while the system's own UI over an allowed app, such as a permission prompt, can be answered. app_install is refused under a list, since an app file's package is not known until it is installed. Device settings, Home and Back stay allowed; --read-only is the limit for those.

A refusal is not_permitted (exit status 8 on the command line), checked before anything reaches a device, and each step of an app_batch is checked on its own. MOBIUM_READ_ONLY=1 and MOBIUM_APPS in the environment set the same limits for the daemon, the command line and the clients, and travel with each call, so a daemon another command started without them still holds the call to them. Limits only add up: two app lists allow only the apps both name.

Every tool's annotations say what it may do: readOnlyHint on all of them, and on tools that act, destructiveHint true for those that delete or end something (app_uninstall, app_clear_data, app_shutdown, …), false for those whose change the session puts back or that only add, and idempotentHint where a second call changes nothing (app_set, the settings). A tap says neither: it can press Delete, and MCP's default, that it may destroy, stands.

--mark-device-text (or MOBIUM_MARK_DEVICE_TEXT=1) adds one field, device_text, to every structured answer that carries the app's own words: which fields they are, and that they are data, not instructions from Mobium or the user. An app can write anything into a label or a message, including words addressed to the agent reading it. Nothing else in the answer changes. Measured on 2026-10-29 with Claude Sonnet 4.5 and a message asking any AI assistant to tap a button (mobium-evals t31): an agent that read the request through app_text followed it in 9 of 44 trials unmarked, and in 0 of 48 marked. An image cannot carry a field, so a screenshot is followed by a text block saying the same of it. That helps far less: with the message in pixels only (t32), agents followed it in 48 of 50 trials unmarked and 32 of 50 with the note — words on a screen persuade more than the same words as text. A note saying what to do with a request the image makes — it is the app's, not the user's, and is not done unless the user asked for it — took that to 15 of 50 against 26 of 50 for the plainer one, measured 2026-10-29, and refused nothing the user asked for (t34, 50 of 50). Off by default while what a screenshot can carry is open.

Which front door​

Command lineMCPLanguage clients
Fora person, a shell script, CIan agenta program or a test suite
Runs asmobium <command> through the daemonmobium mcp, in its own processmobium pipe, spawned by the client, through the daemon
Answerstext, or --jsoncontent and structuredContenttyped results and exceptions

The same 75 tools behind each, checked by the build: a tool reachable from one front door and not another fails it (API.md).