MCP

Appelium exposes a Model Context Protocol (MCP) server for AI clients that need structured crash and test investigation data. The toolset covers crash reports — ranked crash group discovery, crash group details, occurrence statistics, individual crash reports, and the activity logs captured before a crash — as well as test reports: ranked test failure group discovery, failure group details and statistics, individual failing test runs, their activity logs and call stacks, and one-hour presigned URLs for captured screenshots and recordings for multi-modal analysis.

Endpoint

All MCP requests are sent to the same HTTP endpoint:

https://api.appelium.com/v1/mcp

Appelium uses JSON-RPC 2.0 over Streamable HTTP. The transport is stateless, so there is no MCP session ID to create, persist, or refresh.

Authentication

MCP currently supports API key authentication only. Send your Appelium API key in this header:

X-Appelium-Token: <api-token>

Personal API keys can be created in Dashboard under API Access Settings. If you do not have a key yet, follow the steps in Authentication to create one.

Setup

To connect an MCP client to Appelium you only need four values:

Transport: Streamable HTTP
URL: https://api.appelium.com/v1/mcp
Header: X-Appelium-Token
Header value: your personal Appelium API key

Most MCP clients have a server configuration screen or JSON file where you provide the endpoint URL and custom headers. After the connection is saved, the client can call initialize, tools/list, and tools/call against the Appelium MCP server.

Minimal request flow

Create an Appelium API token.
Configure your MCP client to send requests to https://api.appelium.com/v1/mcp.
Add the X-Appelium-Token header with your personal API key.
Initialize the MCP session.
List the available tools.
Call the crash-report or test-report tools you need.

Supported MCP methods

Method	Description
`initialize`	Negotiates the MCP protocol version and returns server capabilities.
`notifications/initialized`	Optional initialization notification. Appelium accepts it as a no-op.
`ping`	Health check that returns an empty object.
`tools/list`	Returns the list of available tools and their input schemas.
`tools/call`	Executes a tool with the provided arguments.

Available crash-report tools

Tool	Purpose
`list_applications`	Lists all applications in the workspace with their id, slug, platform, and current release version.
`get_crash_group`	Returns a crash group together with the latest symbolicated call stack.
`get_crash_group_stats`	Returns occurrence counts, affected device counts, affected OS versions, and the observed date range.
`list_crash_reports`	Lists the most recent crash reports for a crash group.
`get_crash_report_logs`	Returns the activity logs captured before a selected crash report.

Tool arguments

`list_applications`

Use this when you need to discover the available applications in the workspace or look up an application's id or slug before calling other tools.

This tool takes no arguments.

`get_crash_group`

Use this as the entry point when the agent already knows the crash group id or the serial number visible in Dashboard.

Argument	Type	Required	Notes
`id`	integer	No	Global crash group id. Mutually exclusive with `serialNumber`.
`serialNumber`	integer	No	Workspace-scoped crash group serial number. Mutually exclusive with `id`.
`applicationId`	integer	No	Recommended when known. Scopes the returned call stack to the latest crash report of that application.

`get_crash_group_stats`

Use this when the agent needs to understand how widespread a crash group is.

Argument	Type	Required	Notes
`id`	integer	No	Global crash group id. Mutually exclusive with `serialNumber`.
`serialNumber`	integer	No	Workspace-scoped crash group serial number. Mutually exclusive with `id`.
`days`	integer	No	Look-back window. Supported values: `7`, `30`, `90`. Defaults to `30`.

`list_crash_reports`

Use this to inspect recent occurrences after identifying the crash group.

Argument	Type	Required	Notes
`crashGroupId`	integer	No	Global crash group id. Mutually exclusive with `crashGroupSerialNumber`.
`crashGroupSerialNumber`	integer	No	Workspace-scoped crash group serial number. Mutually exclusive with `crashGroupId`.
`limit`	integer	No	Number of reports to return. Allowed range: `1` to `25`. Defaults to `10`.

`get_crash_report_logs`

Use this after list_crash_reports when a specific crash report has activity logs attached.

Argument	Type	Required	Notes
`crashReportId`	UUID	Yes	Crash report id returned by `list_crash_reports`.

Available test-report tools

Tool	Purpose
`resolve_test_run_url`	Resolves a Dashboard test-run URL into a global `testRunId`. Start here when the agent begins from a Dashboard link.
`get_test_run_details`	Returns full metadata for a test run and one-hour presigned media URLs (screenshot, screen recording, accessibility snapshot). Use this before logs or call stacks when you need context.
`get_test_failure_call_stack`	Returns the test call stack (and app-crash call stack when applicable) for a test run. Use this after details when you need the failing frame.
`get_test_run_logs`	Returns the activity logs captured during a selected test run. Use this after details and call stack to understand the surrounding runtime behavior.

Tool arguments

`resolve_test_run_url`

Use this when the agent already has a Dashboard test-run URL and needs the global testRunId before calling the other test-report tools.

Argument	Type	Required	Notes
`dashboardUrl`	string	Yes	Dashboard URL or path of the form `/{workspaceSlug}/apps/{applicationSlug}/test-executions/{testExecutionSerialNumber}/runs/{testRunSerialNumber}`.

`get_test_run_logs`

Use this when you already have a testRunId and want the captured activity logs for that run.

Argument	Type	Required	Notes
`testRunId`	integer	Yes	Test run id returned by `resolve_test_run_url` or another trusted source.

`get_test_failure_call_stack`

Use this to retrieve the symbolicated call stack for a run that captured one.

Argument	Type	Required	Notes
`testRunId`	integer	Yes	Test run id returned by `resolve_test_run_url` or another trusted source.

`get_test_run_details`

Use this to fetch the full metadata for a run, including one-hour presigned media URLs.

Argument	Type	Required	Notes
`testRunId`	integer	Yes	Test run id returned by `resolve_test_run_url` or another trusted source.

Recommended crash investigation flow

For most agent workflows, this sequence is enough:

If you already have a Dashboard test-run URL, call resolve_test_run_url first to get the testRunId.
Call list_applications to discover the available applications and their slugs if needed.
Call get_crash_group with a known crash group id or Dashboard serial number to get the latest symbolicated call stack.
Call get_crash_group_stats to see how often the crash occurs and which OS versions are affected.
Call list_crash_reports to inspect the most recent occurrences.
Call get_crash_report_logs for a report where hasActivityLogs is true.

Recommended test-failure investigation flow

For investigating failing tests, this sequence is usually enough:

If you already have a Dashboard test-run URL, call resolve_test_run_url first to get the testRunId.
Call get_test_run_details to inspect the test metadata, failure description, and attached media URLs.
Call get_test_failure_call_stack to see the failing frame or the app-crash stack behind the failure.
Call get_test_run_logs to review the latest runtime logs around the failure.
Only after that, decide whether you have enough evidence to propose or search for a fix.

Example requests

Initialize the MCP connection:

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

List the available tools:

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

Fetch a crash group by Dashboard serial number:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_crash_group",
    "arguments": {
      "serialNumber": 1452
    }
  }
}

Notes

MCP access is never anonymous. The caller must belong to the target workspace.
Tool responses inherit the caller's workspace and role permissions.
tools/list is the source of truth for the currently available tools and input schemas.