Skip to content

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

  1. Create an Appelium API token.
  2. Configure your MCP client to send requests to https://api.appelium.com/v1/mcp.
  3. Add the X-Appelium-Token header with your personal API key.
  4. Initialize the MCP session.
  5. List the available tools.
  6. 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_top_crash_groups Returns ranked top crash groups for an application, optionally filtered to a single app 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.
resolve_crash_report_url Resolves a Dashboard crash-report URL into stable crash identifiers. Start here when the agent begins from a crash-report link.
get_crash_report_details Returns full metadata and symbolicated call stack for a specific crash report.
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_top_crash_groups

Use this when the agent needs ranked crash-group discovery for a specific application, especially for prompts such as top 10 crash groups affecting app version X.Y.Z.

Argument Type Required Notes
applicationId integer Yes Global application id. Resolve it via list_applications before calling this tool.
applicationVersion string No Optional semantic app version filter (for example 3.4.1).
days integer No Look-back window. Supported values: 7, 30, 90. Defaults to 30.
limit integer No Number of crash groups to return. Allowed range: 1 to 50. Defaults to 10.

Result is a JSON array sorted by impact (crash count descending, then affected device count descending). Each element includes crash-group metadata (crashGroupId, serialNumber, exceptionSymbol, optional fix version) and impact metrics (crashesCount, affectedDeviceCount, date/version bounds, relativeShare).

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.

resolve_crash_report_url

Use this when the agent already has a Dashboard crash-report URL and needs stable ids before calling other crash-report tools.

Argument Type Required Notes
dashboardUrl string Yes Dashboard URL or path of one of these forms: /{workspaceSlug}/apps/{applicationSlug}/crash-groups/{crashGroupSerialNumber}/crash-reports/{crashReportSerialNumber} or /{workspaceSlug}/crashes/{crashGroupSerialNumber}/crash-reports/{crashReportSerialNumber}.

get_crash_report_details

Use this after resolve_crash_report_url when you need the full report metadata and call stack for that exact crash report.

Argument Type Required Notes
crashReportId UUID Yes Crash report id returned by resolve_crash_report_url, list_crash_reports, or another trusted source.

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_execution_url Resolves a Dashboard test-execution URL into a global testExecutionId. Start here when the agent begins from an execution link.
get_test_execution_failure_groups Returns the failure groups in one test execution, ranked by their execution-scoped failure count.
get_test_execution_run_summaries Returns non-skipped test-run summaries for one test execution.
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_execution_url

Use this when the agent has a Dashboard test-execution URL and needs the global testExecutionId before inspecting failure groups or individual runs.

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

The result contains applicationId and testExecutionId.

get_test_execution_failure_groups

Use this to identify which failure groups had the greatest impact within one test execution.

Argument Type Required Notes
testExecutionId integer Yes Test execution id returned by resolve_test_execution_url or another trusted source.

The result is an array of failure-group content sorted by failure count descending. numberOfFailures is calculated only from non-skipped runs in the requested execution, not from the group's lifetime history.

get_test_execution_run_summaries

Use this to inspect the runs in an execution and select a testRunId for deeper investigation.

Argument Type Required Notes
testExecutionId integer Yes Test execution id returned by resolve_test_execution_url or another trusted source.

The result is an array of non-skipped test-run summaries ordered by start date. Each summary includes run and failure-group ids, result and failure data, iteration, locale, duration, test case and executor ids, configuration, and failure screenshot metadata when available.

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.

For most agent workflows, this sequence is enough:

  1. If you already have a Dashboard crash-report URL, call resolve_crash_report_url first to get crashReportId and crashGroupId.
  2. Call get_crash_report_details to inspect metadata and the exact report call stack.
  3. Call list_applications to discover the available applications and their slugs if needed.
  4. Call get_top_crash_groups to identify the highest-impact crash groups for your target application and (optionally) a specific app version.
  5. Call get_crash_group with a known crash group id or Dashboard serial number to get the latest symbolicated call stack.
  6. Call get_crash_group_stats to see how often the crash occurs and which OS versions are affected.
  7. Call list_crash_reports to inspect the most recent occurrences.
  8. Call get_crash_report_logs for a report where hasActivityLogs is true.

For triaging an entire test execution, this sequence is usually enough:

  1. Call resolve_test_execution_url with the Dashboard execution URL to get testExecutionId.
  2. Call get_test_execution_failure_groups to rank failure groups by the number of failed runs in that execution.
  3. Call get_test_execution_run_summaries to choose representative runs from an impactful failure group.
  4. Call get_test_run_details, get_test_failure_call_stack, and get_test_run_logs for the selected runs.

For investigating failing tests, this sequence is usually enough:

  1. If you already have a Dashboard test-run URL, call resolve_test_run_url first to get the testRunId.
  2. Call get_test_run_details to inspect the test metadata, failure description, and attached media URLs.
  3. Call get_test_failure_call_stack to see the failing frame or the app-crash stack behind the failure.
  4. Call get_test_run_logs to review the latest runtime logs around the failure.
  5. 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.