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, including start date, environment, and app version. Pass includeMedia: false to omit screenshots.
get_test_failure_group Looks up one failure group by pasted Dashboard URL, application id + serial number, or id. Returns its metadata, 30-day failure count, affected test cases, and the latest failing run ids. Start here when the agent begins from a failure-group link.
get_test_failure_group_history Returns the history of a failure group across test executions (date, environment, app version, pass/fail) with first-seen date, failure rates, the regression boundary, and environment/app-version breakdowns.
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.
includeMedia boolean No Defaults to true. Set it to false to leave out failure screenshots and their presigned URLs, which makes the response much smaller. Use get_test_run_details to fetch media for a selected run.

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, and configuration.
  • startDate, environmentName, and appVersion. The last two are null when unknown.
  • Failure screenshot metadata when available and includeMedia is not false.

get_test_failure_group

Use this when the user pastes a failure-group link or mentions a failure group number. A single call returns the group and a representative run, so the agent does not need to list every failure group and run summary of an execution.

Identify the group with exactly one of the following:

Argument Type Notes
dashboardUrl string Dashboard URL or path of the form /{workspaceSlug}/apps/{applicationSlug}/test-failure-groups/{testFailureGroupSerialNumber}. Query parameters are ignored.
applicationId + serialNumber integer + integer Failure group numbers (#N in the Dashboard) are unique per application. Use list_applications to find the applicationId.
testFailureGroupId integer Global failure group id returned by other test-report tools.

The result contains:

  • applicationId.
  • testFailureGroup: the group metadata. numberOfFailures covers the last 30 days (failureCountPeriodDays).
  • affectedTestCases: up to 10 test cases with their failed-run counts, plus affectedTestCasesTruncated.
  • latestFailingRun: testRunId, testRunSerialNumber, testExecutionId, testExecutionSerialNumber, testCase, startDate, failureDescription, environmentName, appVersion, and crashReportId.

Pass latestFailingRun.testRunId to get_test_run_details, get_test_failure_call_stack, or get_test_run_logs.

get_test_failure_group_history

Use this to look beyond a single execution: how a failure group behaved across all executions in which its test cases ran, including the executions where they passed. It answers when the failure was first seen, how often it fails, whether it is a new regression, and whether it is tied to one environment or app version.

Argument Type Required Notes
testFailureGroupId integer One of Failure group id returned by get_test_failure_group, get_test_execution_failure_groups, get_test_execution_run_summaries, or get_test_run_details.
dashboardUrl string One of Dashboard URL or path of the form /{workspaceSlug}/apps/{applicationSlug}/test-failure-groups/{testFailureGroupSerialNumber}.
applicationId + serialNumber integer One of Application id and the failure group number (#N) shown in the Dashboard.
days integer No Look-back window: 7, 30 (default), or 90.
limit integer No Number of most recent executions listed in executions. Default 30, maximum 100. Summary and breakdowns always cover the whole window.

The result contains:

  • testFailureGroup: the failure group metadata.
  • summary: firstSeenDate (lifetime), isNewInPeriod, firstFailureInPeriodDate, lastFailureDate, execution counts by outcome, executionFailureRate, run counts, runFailureRate, latestExecution, firstFailingExecution, lastPassingExecutionBeforeFirstFailure, currentFailureStreak, and executionsWithoutFailureSinceLastFailure.
  • environments and applicationVersions: per-environment and per-app-version execution counts, run counts, failure rate, and first/last failure dates.
  • affectedTestCases: test cases that failed with this group in the window (up to 25, see affectedTestCasesTruncated).
  • executions: newest first, each with testExecutionId, serialNumber, date, environments, applicationVersions, run counts, and outcome. The outcome is one of failed, flaky (each test case that failed with this group also passed in the same execution, for example on retry), failed_other_reason, passed, or skipped.

To find a regression boundary, compare the app version and environment of lastPassingExecutionBeforeFirstFailure with firstFailingExecution. This comparison matters most when isNewInPeriod is true.

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.

The result includes testFailureGroupId for failed runs. Pass it to get_test_failure_group_history to see how the failure behaved across executions.

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_failure_group_history for an impactful group to see whether it is new, flaky, or tied to one environment or app version.
  4. Call get_test_execution_run_summaries with includeMedia: false to choose representative runs from an impactful failure group.
  5. Call get_test_run_details, get_test_failure_call_stack, and get_test_run_logs for the selected runs.

When the user pastes a failure-group link or mentions a failure group number:

  1. Call get_test_failure_group with the dashboardUrl, or with applicationId + serialNumber, to get the group and its latestFailingRun.
  2. Call get_test_failure_group_history with the returned group id to see whether the failure is new, flaky, or tied to one environment or app version.
  3. Call get_test_run_details, get_test_failure_call_stack, and get_test_run_logs with latestFailingRun.testRunId, or with a run from a specific execution in the history.

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. Call get_test_failure_group_history with the run's testFailureGroupId to find out whether the failure is new, recurring, flaky, or tied to one environment or app version.
  6. 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.