MCP Server Reference
Inslytic runs a remote Model Context Protocol server, so AI assistants such as Claude, Cursor or VS Code Copilot can read your product analytics. Every tool is read-only and scoped to one project. For an overview and setup walkthrough, see the MCP page.
Endpoint
https://api.inslytic.com/v1/mcp- Streamable HTTP transport, stateless: every request stands on its own, there are no sessions.
- Supports the 2026-07-28 protocol revision and 2025 revisions (2025-11-25 and earlier, via
initialize). The protocol version is negotiated automatically. GETandDELETEreturn405: the server never opens server-initiated streams.- Clients that only speak stdio (such as Claude Desktop) connect through mcp-remote.
Authentication
Send a personal MCP key as a Bearer token. Create one in the dashboard under Settings → MCP; it is shown once, so copy it right away.
Authorization: Bearer ins_sk_your_mcp_key_here- A key belongs to you and to one project. It reads exactly what you can see in the dashboard for that project.
- Keys can be revoked any time in Settings → MCP (admins can revoke anyone's). A key stops working when its owner leaves the organization.
- The project API key used by the SDKs (
ins_…) is public and is rejected here with401and a pointer to Settings → MCP.
Connect a client
Settings → MCP shows these snippets with your key filled in.
claude mcp add --transport http inslytic https://api.inslytic.com/v1/mcp \
--header "Authorization: Bearer ins_sk_your_mcp_key_here"{
"mcpServers": {
"inslytic": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.inslytic.com/v1/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer ins_sk_your_mcp_key_here"
}
}
}
}{
"mcpServers": {
"inslytic": {
"url": "https://api.inslytic.com/v1/mcp",
"headers": {
"Authorization": "Bearer ins_sk_your_mcp_key_here"
}
}
}
}Tools
Time-bound tools accept from and to and echo the exact period they cover. Results are returned as structured content (with an output schema) and as JSON text for older clients. All times are UTC.
| Parameter | Type | Required | Description |
|---|---|---|---|
| from | string | Optional | Start of the period, ISO 8601 (e.g. 2026-10-01T00:00:00Z). Defaults to 30 days before `to`. |
| to | string | Optional | End of the period (exclusive), ISO 8601. Defaults to now. The period can be at most 2 years. |
get_event_taxonomy
The product type and description, the configured event taxonomy (description and lifecycle stage per event), and every event the project has sent with its count and first/last seen time. Call it first: event names are case-sensitive. No parameters.
get_overview
Unique visitors, page views, identified users and bounce rate for the period, the same values for the previous period of equal length, and the % change. A change is null when the previous period has no data to compare against. Parameters: from, to.
get_timeseries
One event over time, with count and unique users per bucket. Buckets are hourly for periods under 2 days, daily under 90 days and weekly beyond; empty buckets are omitted.
| Parameter | Type | Required | Description |
|---|---|---|---|
| event | string | Optional | Exact event name. Defaults to $pageview. |
get_top_events / get_top_pages
Custom events (page views excluded) ranked by count, or pages ranked by views with unique visitors. Parameters: from, to, limit (1–100, default 10).
run_funnel
Visitors per step of an ordered list of events, with conversion from the first step and from the previous step. A visitor counts for a step only after completing the previous steps, in order, within 24 hours.
| Parameter | Type | Required | Description |
|---|---|---|---|
| steps | string[] | Optional | 2–10 event names in order. Pass either steps or funnel_id. |
| funnel_id | string | Optional | Id of a funnel saved in the dashboard (see list_saved_analyses). |
get_retention
Visitors grouped by the week they were first seen in the period, and how many returned in each following week. Use a period of 8–12 weeks. Parameters: from, to.
list_saved_analyses / run_saved_query
list_saved_analyses returns the funnels and queries saved in the dashboard (no parameters). run_saved_query runs a saved query for a period: query_id (required), from, to.
query_events
Read-only ClickHouse SQL against the events table, for questions the other tools don't cover.
| Parameter | Type | Required | Description |
|---|---|---|---|
| sql | string | Required | A single ClickHouse SELECT statement. |
- Use
{from:DateTime64(3)}and{to:DateTime64(3)}for the period; the server fills them in from the arguments. - Only your project's rows are visible, enforced by the database. Filtering with
project_id = {projectId:UUID}is optional. - One
SELECTonly: noSETTINGS,FORMATor table functions, and no tables other thanevents. - At most 10,000 rows;
truncatedistruewhen the result was cut off.
Errors
Problems the assistant can fix (a mistyped event name, an invalid date, rejected SQL, an unknown saved funnel) come back as a tool result with isError: true and a message explaining what to change:
{
"isError": true,
"content": [
{
"type": "text",
"text": "Unknown event \"add_to_kart\" (did you mean \"add_to_cart\"?). Event names are case-sensitive; call get_event_taxonomy for the full list."
}
]
}Unexpected failures return a generic message. A missing, invalid or revoked key returns HTTP 401.
Limits
- 60 tool calls per minute per key, and 300 per minute per project across all keys.
- Over the limit, the tool call returns an error telling the assistant how many seconds to wait. Connecting and listing tools don't count.
- Queries time out after 30 seconds and return at most 10,000 rows.
- Periods can be at most 2 years, the retention period of event data.