# MCP server

Source: https://pulse.mightys.dev/docs/mcp/

A read-only [Model Context Protocol](https://modelcontextprotocol.io) server, so an AI agent can read your Pulse
analytics: which apps you have, how they are doing, and whether a new install already sends signals. It cannot change
anything. Available on every plan, with a rate limit.

## Connect

- Endpoint: `https://pulse.mightys.dev/mcp` (Streamable HTTP, stateless).
- Authentication: a personal read token. Create one in the dashboard (account menu, Access tokens), copy it once, and send it
  as `Authorization: Bearer pulse_pat_...`. The token reads what your account can read in the portal, nothing more, and
  stops working at once when you revoke it, when it expires, or when the account is blocked or deleted.
- Rate limit: 60 requests per minute per token, counted on top of your account's own limit. Over it: HTTP 429 with
  `Retry-After`.
- Without a token, the server answers only the discovery requests (`initialize`, `notifications/initialized`, `ping`
  and `tools/list`), so a client can show the tool list before you add the token. Those requests are limited to 30 per
  minute per address. Every tool call needs the token: without it the answer is HTTP 401, and a wrong token is always 401.

Example client configuration (most MCP clients accept this shape):

```json
{
  "mcpServers": {
    "pulse": {
      "type": "http",
      "url": "https://pulse.mightys.dev/mcp",
      "headers": { "Authorization": "Bearer pulse_pat_..." }
    }
  }
}
```

## Periods and test data

Tools with a `period` accept `today`, `yesterday`, `7d`, `30d` or `90d` (UTC days, today included), or `from` and `to`
as RFC 3339 instants with an offset (for example `2026-11-01T00:00:00Z`; `to` is exclusive). `test_mode` (default
`false`) reads test (debug) signals only instead of real ones. Numbers are the same as in the portal: a session ends
after 30 minutes without a signal.

## Tools

| Tool | Arguments | Answer |
| --- | --- | --- |
| `list_apps` | none | Apps the token can read: id, name, organization, platforms, last signal time. Start here. |
| `get_overview` | `app_id`, `period` (default `7d`), `from`, `to`, `test_mode` | Users, sessions, signals, average session in seconds, new users, top 5 signal types. |
| `top_signals` | `app_id`, `period` (default `7d`), `limit` (1 to 50, default 10), `from`, `to`, `test_mode` | Most frequent signal types with counts, first and last time seen. |
| `signal_breakdown` | `app_id`, `signal_type`, `property`, `period` (default `7d`), `limit` (1 to 50, default 10), `from`, `to`, `test_mode` | Values of one props key or system field (`app_version`, `os_version`, `platform`, `country`, `device_model`, `locale`) for one signal type, with counts and shares. |
| `get_retention` | `app_id`, `period` (default `90d`), `from`, `to`, `test_mode` | Weekly retention cohorts (users, or sessions when the app sends no user). Needs a plan with retention. |
| `get_funnel` | `app_id`, `steps` (2 to 8 signal types in order), `period` (default `30d`), `scope` (`session` or `user`), `window_hours` (1 to 8760, default 24), `from`, `to`, `test_mode` | How many sessions or users reached each step. Needs a plan with funnels. |
| `check_install` | `app_id`, `minutes` (1 to 1440, default 10), `signal_type` (optional) | Whether anything (or that type) arrived in the last minutes, test and real signals: count, last time, SDK names and versions, how many were test signals. Call it right after installing the SDK. |
| `get_schema` | `app_id`, `test_mode` | Signal types of the last 30 days with counts, the props keys of the 8 most frequent types, and the system fields to break down or filter by. |
| `get_errors` | `app_id`, `period` (default `7d`), `from`, `to`, `test_mode` | Errors and crashes: crash-free sessions, crashes, errors and affected users, the same per app version, and the 20 largest error groups. The same numbers as the Errors screen. |

Answers are compact JSON text. A problem (unknown app, a period older than your plan's raw history, a plan without the
report, a busy source) comes back as a tool error with a plain sentence, never a stack trace.
