MCP tools

Updated

Telltale has no chart dashboard. You analyse your app by asking an agent, which calls the tools on Telltale's MCP server. Every tool is scoped to one app, takes that app's numeric app_id, and returns bounded JSON.

Connect your agent

The simplest route is through Scalpels. Install the Scalpels MCP server in your agent and create a token with the Call installed apps ability; see Use Scalpels from your agent. Your agent can then list the MCP-enabled products your team runs, including Telltale, and relay calls to it. Each call carries your identity and role: team Owners, Admins and Members can all use Telltale's tools. How that relay works is described under Console.

Telltale's MCP server is served at /mcp on your deployment, with its destructive tools on a separate /mcp/destructive endpoint. Telltale does not have a screen for minting its own MCP tokens.

Then ask in plain language, for example:

Which errors are new since version 2.3.0 of our mobile app, and how many installs hit them?

What share of active installs is on the latest release?

Finding your app

Tool	What it returns
`apps`	Up to 100 apps with their id, name, latest retained event, versions live in the last 30 days and cumulative client drops. Start here to get the `app_id`.
`ingest_health`	Client drops, known rejections, rate-limit hits and recently seen client versions over `days` (1 to 90, default 30).

Usage and releases

Tool	What it returns
`active_users`	DAU, WAU and MAU as of a UTC date (`as_of`, `YYYY-MM-DD`, default today), with version and platform breakdowns.
`release_adoption`	Daily active-install counts and shares by app version over `days` (1 to 90).
`event_counts`	Event or screen counts (`metric`: `event` or `screen`) over `days`, optionally broken down by `version`, `platform`, `os` or `locale`.
`retention`	First-seen-week cohorts and weekly returning-install retention over `weeks` (0 to 12, default 8).

These read durable daily aggregates, so they keep working after raw events are pruned.

Behaviour

Tool	What it returns
`screen_flow`	The most common screen-to-screen transitions and session entry and exit screens over `days`, up to `limit` (1 to 50).
`funnel`	Ordered per-install conversion and drop-off for 1 to 10 event names in `steps`, within `window_minutes` (default 1440, up to 10080) of the first step, over `days`.
`install_timeline`	Up to 200 retained events, in order, for exactly one `install_id` or one `session_id`.

These read retained raw events, so they can only look back as far as the retention window (90 days by default; see Configuration).

sessions returns session count, average, median and 95th-percentile length, and average screens per session over days. It reads session records, which the raw-event prune does not delete.

Errors

Tool	What it returns
`errors`	Error groups seen in the last `days` (default 30), up to `limit` (1 to 50), with occurrences, installs affected, first and last seen times and versions. Pass `new_since_version` to flag groups that first appeared after that version.
`error_detail`	One group by its 64-character `fingerprint` (from `errors`), with its totals, a bounded sample error with stack data and the distribution of context it occurred in.

Errors are grouped by fingerprint. These are PHP errors reported through Laravel, not native crashes.

Administration tools

Three tools change data. Each is two-phase: the first call returns a preview of what would happen, and nothing changes until it is confirmed with a single-use confirmation.

Tool	What it does
`revoke_install`	Revokes one install's token so that device can no longer send or re-register. Its history is kept.
`delete_install`	Deletes one install with its raw events and sessions. The preview reports how many would go. Daily aggregates are preserved.
`rotate_ingest_key`	Invalidates an app's ingest value and returns the replacement exactly once, like the dashboard's Rotate ingest value.

See Privacy and data for when to revoke and when to delete.