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

Sixteen tools over the data you already have: overviews, event schemas, users, funnels, retention, paths, sessions, heatmaps, saved insights, and annotations. 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."

That last one writes, and needs a token with the read_write scope. Everything else is read-only.

Create a token

In the app, open Account → Personal access tokens.
Create a token, give it a name you will recognise later ("laptop Claude", "CI"), pick a scope, and optionally an expiry date.
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.

Two scopes, and the difference is one verb:

Scope	What it allows
read	Everything read-only — every tool on this page except create_annotation. The right default for an agent you are asking questions of.
read_write	Read, plus creating annotations. That is the whole of it: there is no scope that can create API keys, invite members, create projects, or delete anything.

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

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.

Tool	What it returns
list_projects	Every project the token's owner can read, with its organization and project slug — the arguments every other tool takes.
get_overview	Headline 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_names	The distinct event names in the project, busiest first and capped at 100 — the vocabulary to filter and build funnels with.
get_event_schema	For 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_events	A sample of up to 20 recent events with their properties — enough to see the shape of the data, not a dump of it.
query_users	Up 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.
get_user	One person: their profile properties, their last 20 events, and their session stats.
run_funnel	Two to five steps, loose or strict ordering, a conversion window, and an optional breakdown by property. Returns users per step, conversion from the previous step and from the start, and median time to convert.
get_retention	Day or week cohorts, optionally narrowed to one event — who came back, and how many periods later. At most 12 cohorts by 12 periods.
get_paths	The 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.
get_session_stats	Sessions, median duration, events per session, bounce rate, and the same numbers bucketed as a series.
list_heatmap_pages	The pages with the most clicks, ranked and capped at 25 — the picker for the summary below.
get_heatmap_summary	For one page: the 25 most-clicked elements, how far down people scrolled, and the split across desktop, tablet, and mobile.
list_saved_insights	The funnels, paths, retention, and session questions your team has already saved, up to 50 of them.
list_annotations	The dated notes on a project's timeline — deploys, launches, incidents — up to 100 in the window.
create_annotationwrite	Write a dated note onto a project's timeline. The only tool that writes anything, and it needs a read_write token.

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.

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.
An agent sees exactly what the token's owner sees. Organization membership is checked on every single call, and a project you are not a member of 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, and only with a read_write token. API keys, members, projects, and deletions 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.