Skip to content

MCP

Appelium exposes a Model Context Protocol (MCP) server for AI clients that need structured crash investigation data. The current MCP toolset is focused on crash reports and gives agents direct access to crash group details, occurrence statistics, individual crash reports, and the activity logs captured before a crash.

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 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
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

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.

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.

For most agent workflows, this sequence is enough:

  1. Call get_crash_group with the crash group serial number from Dashboard.
  2. Call get_crash_group_stats to see how often the crash occurs and which OS versions are affected.
  3. Call list_crash_reports to inspect the most recent occurrences.
  4. Call get_crash_report_logs for a report where hasActivityLogs is true.

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.