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.
  • GET and DELETE return 405: 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 with 401 and a pointer to Settings → MCP.

Connect a client

Settings → MCP shows these snippets with your key filled in.

Claude Code
claude mcp add --transport http inslytic https://api.inslytic.com/v1/mcp \
  --header "Authorization: Bearer ins_sk_your_mcp_key_here"
Claude Desktop · claude_desktop_config.json
{
  "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"
      }
    }
  }
}
Cursor · ~/.cursor/mcp.json
{
  "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.

ParameterTypeRequiredDescription
fromstringOptionalStart of the period, ISO 8601 (e.g. 2026-10-01T00:00:00Z). Defaults to 30 days before `to`.
tostringOptionalEnd 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.

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

ParameterTypeRequiredDescription
stepsstring[]Optional2–10 event names in order. Pass either steps or funnel_id.
funnel_idstringOptionalId 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.

ParameterTypeRequiredDescription
sqlstringRequiredA 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 SELECT only: no SETTINGS, FORMAT or table functions, and no tables other than events.
  • At most 10,000 rows; truncated is true when 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.