longarm MCP Server

longarm exposes a streamable HTTP MCP server for agent integrations.

Endpoint

http://<host>:<mcpPort>/mcp

Health check:

GET /mcp

Example response:

{ "status": "running", "transport": "mcp" }

Authentication

If token auth is enabled, MCP requests must include:

Authorization: Bearer <token>

If auth fails, the server returns:

{ "error": "Missing or invalid bearer token" }

Protocol details

transport: streamable HTTP over POST /mcp
JSON-RPC version: 2.0
MCP protocol version returned by longarm: 2025-06-18
supported RPC methods: initialize, ping, tools/list, tools/call
initialize responses include an Mcp-Session-Id header

Minimal calls

`initialize`

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

`tools/list`

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

`tools/call`

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "open_app",
    "arguments": {
      "packageName": "com.android.settings"
    }
  }
}

Tool availability

Tool availability depends on app settings and subscription state.

Always available:

screen_info
current_window
tap
long_press
open_app
open_intent
app_functions_query
app_function_call
batch_list
batch_get
batch_save
batch_delete
batch_run
batch_run_inline
batch_status
batch_history_list
batch_history_get
batch_history_export
batch_history_delete

Plus only:

swipe
pinch
two_finger_swipe
rotate

Only when UI inspection is enabled and auth remains enabled:

ui_tree
ui_find
ui_wait
ui_action
ui_set_text
ui_scroll

Recorded batch tasks

When a user stops a recording in the Batch tab, longarm saves the captured steps as an ordinary, editable batch task. Recorded tasks have the same JSON shape and behavior as manually authored tasks — there is no separate raw source or revision lifecycle.

Agents use the standard batch tools for recorded tasks: batch_list and batch_get to inspect them, batch_save to update or copy them, and batch_run to execute them. If the original sequence should be preserved, save the edited version with a new id instead of updating the existing task.

Result shape

Tool calls return content (one JSON string item), structuredContent (the same result as JSON), and isError: true when the tool-level result failed.

Example successful result:

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\":true}"
    }
  ],
  "structuredContent": {
    "success": true
  }
}

Example tool-level failure:

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\":\"Batch task not found\"}"
    }
  ],
  "structuredContent": {
    "error": "Batch task not found"
  },
  "isError": true
}

MCP tool calls also appear in the Logs view with method MCP and paths such as tools/call/open_app.

Core tool arguments

`screen_info` / `current_window`

Both take no arguments ({}). current_window returns the foreground window’s package name and a best-effort, nullable activity name; the accessibility service must be enabled.

{
  "packageName": "com.android.settings",
  "activityName": "com.android.settings.Settings"
}

`tap`

{ "x": 540, "y": 1200, "duration": 50 }

Also supports selector-based tap:

{
  "target": { "text": "Sign in", "role": "button" },
  "mode": "semantic_then_gesture"
}

`long_press`

{ "x": 540, "y": 1200, "duration": 1000 }

Plus gestures

// swipe
{ "startX": 540, "startY": 1800, "endX": 540, "endY": 600, "duration": 300 }

// pinch
{ "x": 540, "y": 1200, "startSpread": 400, "endSpread": 100, "angle": 0, "duration": 400 }

// two_finger_swipe
{ "startX": 540, "startY": 1800, "endX": 540, "endY": 600, "spread": 200, "duration": 400 }

// rotate
{ "x": 540, "y": 1200, "radius": 200, "startAngle": 0, "endAngle": 90, "duration": 600 }

`open_app`

{ "packageName": "com.android.settings" }

`open_intent`

{
  "action": "android.intent.action.VIEW",
  "data": "https://example.com"
}

Supported fields: action (required), data, mimeType, packageName, className, categories, extras.

`app_functions_query`

Discovers AppFunctions from Android apps visible to longarm. All arguments are optional:

{
  "packageNames": ["com.example.notes"],
  "schemaCategory": "productivity",
  "schemaName": "createNote",
  "minSchemaVersion": 1,
  "maxResults": 100
}

The result includes the exact functionId, enabled state, and parameter/return metadata needed for a call. Android AppFunctions support and authorization are required; accessibility is not.

`app_function_call`

{
  "packageName": "com.example.notes",
  "functionId": "createNote",
  "arguments": { "title": "Groceries" }
}

Arguments are validated and encoded from the queried AppFunction metadata. The in-app Agent advertises and executes these same tool definitions through the same executor as MCP.

UI tools

Selector schema fields: nodeId, revision, text, contentDescription, viewId, className, role, packageName, index, state, ancestor, descendant.

// ui_tree
{ "window": "active", "maxDepth": 30, "maxNodes": 1000, "includeInvisible": false, "compact": false }

// ui_find
{ "selector": { "text": "Sign in", "role": "button" }, "limit": 20 }

// ui_wait
{ "selector": { "text": "Welcome" }, "condition": "exists", "timeoutMs": 5000, "stableForMs": 0 }

// ui_action
{ "selector": { "text": "Sign in" }, "action": "click", "fallback": "gesture" }

// ui_set_text
{ "selector": { "role": "input", "index": 0 }, "text": "[email protected]", "submit": false }

// ui_scroll
{ "selector": { "role": "list", "index": 0 }, "direction": "forward" }

Batch tools

Batch task structure and runtime behavior are documented in Batch Tasks.

Notable MCP-specific behavior:

batch_run and batch_run_inline return immediately with runId and status: "processing"
batch_run and batch_run_inline accept an optional keepScreenOn boolean (default false) that holds the screen on until the run ends; the power button still turns the screen off
batch_status returns current runner state:

{
  "state": "idle",
  "currentTaskId": null,
  "currentRunId": null,
  "currentStepIndex": 0,
  "totalSteps": 0
}

batch_history_export returns a base64 ZIP payload, not raw binary:

{
  "runId": "run_123",
  "zipBase64": "UEsDB..."
}

Longarm MCP Server