Connect AI agents (MCP)

Tidings speaks Model Context Protocol, so Claude, Cursor, Windsurf, or anything else that speaks MCP can read your product data directly. Point the client at one endpoint, give it a personal access token, and your analytics become something you ask questions of in plain language instead of clicking through.

What you get

Thirty-seven tools over the data you already have: overviews, event schemas, users, funnels, retention, the people behind both, paths, sessions, heatmaps, saved insights, segments, dashboards, annotations, and alerts. The agent picks the ones it needs and composes them — which is the point. "Why did signups drop?" is not one query; it is an overview, then the event names, then a funnel, then a breakdown, and an agent will run all four before it answers.

Things people actually ask it:

  • "Why did signups drop last week?"
  • "Which step of the checkout funnel loses the most mobile users?"
  • "Annotate the chart with today's release."
  • "We just shipped 1.6 — set up a segment, the onboarding funnel, and a dashboard for it."

The last two write, and need a token with the matching grants — annotations for the first, segments, insights and dashboards for the second. Everything else is a read, which needs no grant, and nothing can be deleted through the server at all.

Create a token

  1. In the app, open Account → Personal access tokens.
  2. Create a token, give it a name you will recognise later ("laptop Claude", "CI"), pick its projects and write grants, and optionally an expiry date.
  3. Copy it. Tokens look like tk_… and are shown once — they are hashed at rest, so there is no screen that can show it to you again. Lost one, make another.

A token is limited on two axes: which projects it can see, and which areas it can write in. Access is always the intersection of what you can see and what the token allows, so a token never outlives a membership you lose. A new token defaults to every project and no writes — a read-only token, the right default for an agent you are asking questions of.

PermissionWhat it allows
ProjectsAll projects you belong to, now and later — or a picked set. A token limited to certain projects sees only those in list_projects, answers "Unknown project" for any other, and cannot read organization-wide routes (the org overview and dashboard, members, billing).
annotationscreate_annotation — and creating annotations over the REST API.
segmentscreate_segment and update_segment.
insightssave_funnel, save_insight and update_saved_insight.
dashboardsadd_dashboard_tile, apply_dashboard_template, update_dashboard_tile and remove_dashboard_tile.
alertscreate_alert, update_alert and test_alert — and creating and editing alerts over the REST API.

Reads need no grant, and the only thing a grant can remove is a dashboard tile. No grant deletes a segment, a saved insight, an annotation or an alert, and none creates API keys, invites members or creates projects. tools/list answers only the tools the token may call, so an agent is never offered a write that would refuse it; a write without its grant is refused with a sentence naming the grant to add.

A token is a credential for your account, so treat it like one: keep it out of repositories and screenshots, put it in a config file your agent reads rather than in a prompt, and revoke it from the same page the moment a laptop goes missing or a contract ends. Revoking takes effect on the next request. Its grants and projects can be changed on that page too, without re-pasting the token anywhere: the agent gets the new scope on its next call, and a token can never change its own scope. Its expiry cannot be extended — that takes a new token. An expiry date is worth setting when you know the answer to "how long does this need to work?".

Personal access tokens work on the read API too, as Authorization: Bearer tk_…. The app login token (Authorization: Token …) is a different scheme and is refused by the MCP endpoint — with a hint saying so, rather than a bare 401.

Claude Code

One command. Swap in the token you just copied:

terminal
claude mcp add --transport http tidings https://api.tidingshq.com/api/v1/mcp/ --header "Authorization: Bearer tk_your_token"

Check it connected with claude mcp list — Tidings should report as connected, with its tools listed. Then ask it something:

> Look at my Tidings data for the last 14 days and tell me which step of the onboarding funnel is leaking the most users, split by device.

Claude Desktop, Cursor, Windsurf, and others

Clients that take a JSON config want the same three facts — a name, a URL, and a header. Add this to the MCP section of your client's config file:

mcp config
{
  "mcpServers": {
    "tidings": {
      "url": "https://api.tidingshq.com/api/v1/mcp/",
      "headers": {
        "Authorization": "Bearer tk_your_token"
      }
    }
  }
}

Some clients still only speak stdio, the local-process transport. Those can bridge to an HTTP server with mcp-remote, run as the command:

terminal
npx mcp-remote https://api.tidingshq.com/api/v1/mcp/ --header "Authorization: Bearer tk_your_token"

Under the hood it is MCP's Streamable HTTP transport in stateless mode: JSON-RPC 2.0 over POST https://api.tidingshq.com/api/v1/mcp/, plain JSON responses, no SSE stream and no session to keep alive. Protocol versions 2024-11-05 through 2025-06-18 are supported, so a client that pins an older one still works.

Instructions for the agent

Connecting the server gives the agent thirty-seven tools and one paragraph about them. This file gives it the rest: which tool to start with, how to pick the right one for a question, and how to read a capped, UTC, sampled answer. Paste it into CLAUDE.md, AGENTS.md or your client's rules — it holds no token, so it can live in the repository — or fetch it from /docs/mcp/AGENTS.md.

AGENTS.md
# Tidings analytics (MCP)

The Tidings MCP server (`tidings`) is connected. Tidings is product analytics: the app sends events (`signup_completed`, `page_view`, …) with a `distinct_id` per person, and these tools read them back. Use them whenever the question is about what users did, how many, where they dropped off, or whether they came back.

## Start

- Call `list_projects` first. Every other tool takes the `org` and `project` slugs it returns; never guess a slug.
- With one project, use it. With several, ask which one unless the question names it.
- Call `get_overview` before anything specific: the totals, the previous window and the top event names tell you what the product calls things in its own data.
- Before filtering or breaking down on a property, call `get_event_schema`. It is the only way to know a key exists and whether its values are strings or numbers. Do not guess property names.

## Picking the tool

- How much, how many, trend → `get_overview` (events, users, a series of up to 90 points).
- Which events exist, what a given event carries → `list_event_names`, `get_event_schema`.
- What happened just now, show me examples → `recent_events` (20 at most; the one tool that includes `$` internals).
- Where do people drop off → `run_funnel` with 2–5 steps; `window_days` bounds the time from step 0; `breakdown` splits by a property (top 5 + Other), read off step 0 — pass `breakdown_step` when only a later step carries it (`product` on a purchase); people who never reached that step are `(not set)`. Version-like breakdown values come back in version order, newest first, and `new: true` marks a value first seen in the window.
- Did a conversion rate change after a date (a release, a campaign) → `run_funnel` with `over_time: "day"|"week"`: its `series` groups people by the day or week they entered, with each step's count and the rates per point (at most 120). Recent points have had less time to convert.
- Who are those people → `funnel_users` (one step, converted or dropped), `retention_users` (one cohort cell), `query_users` (a filtered list), `get_user` (one person).
- Do people come back → `get_retention` (weekly cohorts over 84 days by default).
- What do people do after X → `get_paths`.
- How long are visits, bounce rate → `get_session_stats`.
- Where do people click, how far do they scroll → `list_heatmap_pages`, then `get_heatmap_summary`.
- What has the team already saved or noted → `list_saved_insights`, `list_segments`, `list_dashboard_tiles`, `list_annotations`.
- What is being watched, and has it gone off → `list_alerts` (each alert's state: ok, firing or unknown), then `get_alert_events` for what one alert did.
- Is my instrumentation arriving → `check_events` (each expected event and property key, over the last 60 minutes by default).

## Setting Tidings up for the team

Each write needs its area's grant on the token — annotations, segments, insights, dashboards or alerts — and `tools/list` only shows the tools your token may call; if a write you need is missing, tell the user which grant to add rather than working around it. A token may also be limited to certain projects: `list_projects` shows only those. Use the writes when the user asks you to set something up, never on your own initiative. A token can rearrange and remove dashboard tiles, but never delete segments, saved insights, annotations or alerts.

- `create_annotation` — a dated note on the project's timeline ("v1.6 released").
- `create_segment` / `update_segment` — a named group of people, in `query_users`' filter vocabulary.
- `save_funnel` — save a funnel with `run_funnel`'s arguments; run it first and save what produced the answer.
- `save_insight` / `update_saved_insight` — save a funnel, paths, retention or sessions question under Insights.
- `add_dashboard_tile` — pin a chart, or a saved funnel/retention/sessions insight by its id, to the custom dashboard (check `list_dashboard_tiles` first). For a rate shown as one number, pin `type: "ratio"` with a `numerator` and a `denominator`, each `{event_name, filters?, measure}` — e.g. `trial_started` users over `paywall_shown` users. A tile follows the dashboard's range unless you pin its own `range`: `{days: 1|7|30|90}`, `{start, end}` (end exclusive), `{since: "YYYY-MM-DD"}` or `{since_annotation: <id from list_annotations>}` — only when the user asks for a tile that keeps its range ("since launch").
- `apply_dashboard_template` — add a ready-made dashboard from `list_dashboard_templates`.
- `update_dashboard_tile` — move, resize or rename a tile (`layout`, `label`), pin or clear its `range` (`null` clears), or switch its `compare`/`measure` (on a ratio tile, its `numerator`/`denominator`/`format`); only the fields you pass change.
- `remove_dashboard_tile` — remove one tile; the result carries the whole tile, so `add_dashboard_tile` can put it back.
- `create_alert` — be told when a number crosses a line or leaves its usual range: a stat or ratio `query` (the `add_dashboard_tile` vocabulary), a `period` (60, 360, 1440 or 10080 minutes), and either `kind: "threshold"` with a `condition` and `threshold` — "crash > 0 in the last hour" is `{type: "stat", event_name: "crash"}`, period 60, `gt` 0; "new installs down more than 30 % vs the previous day" is period 1440, `change_down_pct` 30 — or `kind: "anomaly"` (`sensitivity` 2–4 standard deviations, `direction`). Notifies org members by email and/or a signed https webhook; the webhook secret is returned once. Check `list_alerts` first, then `test_alert` to prove delivery.
- `update_alert` — rename, pause (`enabled: false`), change recipients, threshold, sensitivity, period or cooldown; what an alert watches cannot change — create a new one instead.

A release, for example version 1.6 of an app:

1. `create_annotation` on the release day.
2. `create_segment` "Users on 1.6" — `person_property app_version eq 1.6`, or `did_event` on an event only 1.6 sends.
3. `save_funnel` / `save_insight` for the onboarding funnel and a paths comparison (paths with `breakdown_event` + `breakdown_property: app_version`).
4. `add_dashboard_tile` to pin them.

To tidy a dashboard, `list_dashboard_tiles`, then `update_dashboard_tile` (layout) or `remove_dashboard_tile`; never remove a tile you were not asked to.

After adding or changing events, call `check_events` with the names and property keys you expect, and confirm they arrive before telling the user it works. When you are done, tell the user what you created, by name, with the URLs the tools returned.

## Reading the answers

- All times are UTC. Every time-scoped tool takes `days` (default 30) or `start`/`end`, and echoes the window and bucket `interval` it actually applied. Report that, not the one you asked for.
- Outputs are capped (20 recent events, 25 users, 90 series points, 40 schema events) and each tool states its cap. A full-looking list is truncated: narrow the question rather than paging or asking for everything.
- Event names starting with `$` are the SDK's own instrumentation (`$click`, `$scroll`, `$identify`). They are excluded from every aggregate unless you name one explicitly.
- The team's own devices and test accounts (`list_internal_identities`) are excluded from every aggregate, named event or not. Pass `include_internal: true` only when the user asks to include them; `recent_events` and `get_user` always show them.
- A result marked `sampled` was computed on a sample of users and scaled back up. Say so when quoting its counts.
- A tool error says what was wrong. Read it and correct the call once; do not retry the same arguments.

## Answering

- Lead with the number and its window ("Signups: 412 in the last 7 days, down 18% on the week before"), then the one comparison or split that explains it, then what you would check next.
- Quote figures as returned; round percentages to whole numbers. Never invent a figure the tools did not return.
- A typical question takes three to five calls. If you need more, say what you are looking for and why.
- Do not paste raw event rows or lists of distinct ids into the answer unless asked. Summarise, and offer to show them.
- Distinct ids and person properties may be personal data. Do not copy them into files or other tools beyond what the user asked for.

The tools

Every time-scoped tool takes either days (30 by default, 365 at most) or an explicit start and end in UTC ISO form, plus an interval of hour, day, or week — the same range vocabulary the app's own charts use. get_retention is the one exception, defaulting to 84 days so a weekly cohort grid has cohorts in it.

ToolWhat it returns
list_projectsEvery project the token's owner can read, with its organization and project slug — the arguments every other tool takes.
get_overviewHeadline totals for a project, the same numbers against the previous window, the top event names, and a time series of up to 90 points.
list_event_namesThe distinct event names in the project, busiest first and capped at 100 — the vocabulary to filter and build funnels with.
get_event_schemaFor each event, the property keys it carries, their types, and how often each one is actually filled in. Up to 40 events by 40 keys.
recent_eventsA sample of up to 20 recent events with their properties — enough to see the shape of the data, not a dump of it.
query_usersUp to 25 users, searched and filtered the way the Users page filters them: event counts, first and last seen, person properties, did / did not do an event — optionally inside a saved segment.
get_userOne person: their profile properties, how they first arrived (entry page, referrer, campaign, device), which of the last 90 days they were active, their session stats, and their last 20 events.
run_funnelTwo to five steps, loose or strict ordering, a conversion window, an optional breakdown by property (read off step 0, or off the step breakdown_step names when only a later step carries it; breakdown_limit keeps 5–20 values, and version-like values come back in version order, newest first), and an optional saved segment. Returns users per step, conversion from the previous step and from the start, and median time to convert; a breakdown value first seen in the window is marked new, and up to five such values are kept even below the top. With over_time (day or week) it also returns the conversion per entry day or week across the window — for "did this change after the release?"
funnel_usersThe people behind one funnel step — everyone who reached it, or only those who stopped there — with the full count and up to 25 of them, most recent first.
get_retentionDay or week cohorts, optionally narrowed to one event — who came back, and how many periods later. At most 12 cohorts by 12 periods.
retention_usersThe people behind one retention cell — who in a cohort came back in a given period, or who did not — with the full count and up to 25 of them.
get_pathsThe top transitions from a starting event — up to 40 of them — so you can see what people actually do next, or the whole node-and-link graph instead with the full flag. One event can be split by a property, such as screens by app version.
get_session_statsSessions, median duration, events per session, bounce rate, and the same numbers bucketed as a series.
list_heatmap_pagesThe pages with the most clicks, ranked and capped at 25 — the picker for the summary below.
get_heatmap_summaryFor one page: the 25 most-clicked elements, how far down people scrolled, and the split across desktop, tablet, and mobile.
list_saved_insightsThe funnels, paths, retention, and session questions your team has already saved, up to 50 of them.
list_segmentsThe project's saved segments — named groups of people — up to 50. Every tool that takes a segment takes one of these ids.
list_internal_identitiesThe team's own devices and test accounts, marked in the project's Settings — read-only. Their events are left out of every number the tools return unless a call passes include_internal: true.
list_dashboard_tilesWhat is pinned to the project's custom dashboard, in order, with each tile's id — so an agent checks before it pins a second copy.
list_dashboard_templatesThe ready-made dashboards that can be added, and whether your events carry the properties each one needs.
list_annotationsThe dated notes on a project's timeline — deploys, launches, incidents — up to 100 in the window.
list_alertsThe project's alerts, up to 25: what each watches, its rule, who it notifies, and its state — ok, firing, or unknown.
get_alert_eventsWhat one alert did, newest first, up to 20: when it fired, recovered, could not be evaluated, or was tested, and whether each email and webhook was delivered.
check_eventsWhether the events and property keys you expect arrived in the last hour (or up to a day): counts, users, last seen, and how many rows carry each key. For confirming new instrumentation before calling it done. Rows from your internal identities are reported apart as internal_count, so a test device's events still show up.
create_annotationwriteWrite a dated note onto a project's timeline.
save_funnelwriteSave a funnel as a named insight the team can open under Insights → Funnels. Same arguments as run_funnel plus a name.
save_insightwriteSave a funnel, paths, retention, or sessions question as a named insight under Insights. It stores the question, never a date range.
update_saved_insightwriteRename a saved insight or replace its question. Its kind stays what it was.
create_segmentwriteSave a named group of people — “Users on 1.6” — in the same filter vocabulary as query_users.
update_segmentwriteRename a segment or change who is in it. Every view narrowed to it follows.
add_dashboard_tilewritePin a chart to the project's custom dashboard, or a saved funnel, retention, or sessions insight by its id. A ratio tile is one rate, a numerator over a denominator, each an event, filters and a measure (trial_started users over paywall_shown users). A breakdown tile, or a timeseries with a breakdown, takes top_n (5–20; default 10 rows on a breakdown tile, 5 lines on a timeseries) and sort (auto, count or value). Up to 20 tiles. Each tile is sized by its type and placed in the first free slot, unless you pass an optional layout. A tile follows the dashboard's range unless it pins its own range: the last 1, 7, 30 or 90 days, a fixed date span, or since a date or an annotation.
apply_dashboard_templatewriteAdd every tile of a ready-made dashboard, or none of them when they would not fit.
update_dashboard_tilewriteMove, resize, or rename one tile, switch what it compares or counts, or pin or clear its own range. Only the fields passed change; a tile's type never does.
remove_dashboard_tilewriteRemove one tile. The answer carries the whole tile, so it can be added back exactly where it was.
create_alertwriteWatch a number and notify the team: “crash > 0 in the last hour”, “new installs down more than 30% vs the previous day”, or an anomaly against the previous 14 periods. The number is a stat or ratio tile; notifications go by email to organization members and to a signed https webhook. Up to 25 per project.
update_alertwriteRename or pause an alert, or change who it notifies, its threshold, sensitivity, period, or cooldown. What it watches never changes — create a new one instead.
test_alertwriteEvaluate an alert now and send a test notification on every channel, without changing its state — to prove the email or webhook arrives.

There is deliberately no raw export tool. An agent that can pull a million rows will pull a million rows, spend its whole context on them, and answer worse than one that asked for an aggregate. When you do want the rows themselves, the CSV export in the app is the tool for that — it streams, and it is not competing for a context window.

Let the agent set up your views

The agent that ships your app is also the one that knows what it just instrumented. Give it a token with the right write grants and it can leave the team a place to look, not just a pull request: a note on the release day, a segment for the people on the new version, the funnel and paths worth watching, and the dashboard they are pinned to.

The release recipe below uses all four grants — annotations, segments, insights and dashboards. A token for one app's agent should also be limited to that app's project, so the agent shipping the iOS app cannot touch the web project's views.

> We're shipping 1.6 of the iOS app today. Set Tidings up for it: mark the release, a segment for 1.6 users, the onboarding funnel for them, and pin it to the dashboard.

That is four calls, each one using the id the one before it returned:

tool calls
create_annotation   {"date": "2026-10-21", "text": "iOS 1.6 released"}
create_segment      {"name": "Users on 1.6", "filters": [{"field": "person_property",
                     "key": "app_version", "operator": "eq", "value": "1.6"}]}
save_funnel         {"name": "Onboarding on 1.6", "segment": "<id from create_segment>",
                     "steps": ["app_opened", "account_linked", "push_opened"]}
add_dashboard_tile  {"type": "funnel", "source_insight": "<id from save_funnel>"}

A paths comparison is save_insight with a paths config split by the version property, and a ready-made board is apply_dashboard_template. Every write answers with the app URL of what it made, so the agent can hand you links rather than descriptions. Before it tells you the new events work, check_events confirms they actually arrived, with the properties it expected. The agent can rearrange and remove dashboard tiles — leaves nothing else points at, and each removal hands the whole tile back so it can be re-added — but it can never delete a segment, a saved insight or an annotation: tiles and shared links reference those by id, so removing one stays something a person does in the app.

Limits & privacy

  • 120 requests per minute per token. An agent exploring a question makes a handful of calls, not hundreds; the limit is there for the loop that goes wrong.
  • Every output is capped so it fits in a context window — 20 recent events, 25 users, 20 events on a profile, 90 points of a series. The caps are part of the design, not a quota you can raise.
  • Your internal identities — the team's devices and test accounts — are left out of every aggregate, exactly as in the app. Every tool that counts takes include_internal: true to put them back; recent_events and get_user always show them.
  • An agent sees at most what the token's owner sees, and only the token's projects when it is limited to some. Organization membership is checked on every single call, and a project you are not a member of — or one outside the token — is indistinguishable from one that does not exist, so a token cannot be used to discover which organizations or projects exist.
  • Nothing is writable except annotations, segments, saved insights, dashboard tiles, and alerts, and each only with its grant on the token. Only dashboard tiles can be removed — never segments, saved insights, annotations or alerts — and API keys, members, and projects are not reachable over MCP at all.

On the data-protection side, the honest framing is this: connecting an agent does not change who may see your data, but it does change where it goes. The tools hand your agent the same event data, distinct ids, and person properties you can already read in the app — and your agent then sends that to whichever model provider it runs on. If your events carry personal data, that is a processor you are choosing, and what the agent does with the results is yours to answer for. Two habits make it easy: keep personal data out of event properties in the first place (see Identity for hashing ids instead of sending emails), and give each agent its own token so you can revoke exactly one thing.

Coming later

Two things are known gaps rather than decisions: OAuth sign-in, so a hosted agent can connect without you pasting a token anywhere, and streaming, so a long-running query can report progress instead of going quiet. Both are planned. Neither changes the tools above.