MCP (AI access)

I use TrueMetriks, a server-side tracking and conversion attribution platform.
It offers MCP access, which lets an AI client read my analytics directly. Walk
me through connecting my AI client to it, step by step.

BEFORE ANYTHING ELSE, ask me these two things and wait for my reply:

  1. Which AI client I want to connect (for example Claude Desktop, Claude Code,
     Cursor, or something else).
  2. My TrueMetriks MCP key.

Tell me exactly where to get the key:

  - Sign in at https://app.truemetriks.com
  - Open "Settings" for the site I want (the site's OWN settings, NOT Account
    Settings), then click the "Integrations" tab.
  - In the tile grid, after "Webhooks", click the "MCP (AI access)" tile.
  - If my workspace has more than one site, pick the site under "Site this key
    reads" first. A key reads exactly ONE site.
  - Click "Generate key" and copy the key from the dialog.
  - IMPORTANT: the key is shown ONCE and cannot be looked up again. Tell me to
    paste it somewhere safe, such as a password manager, before closing the
    dialog. If it is lost, the only fix is to generate a new one, which stops
    the old one working immediately.
  - Only workspace OWNERS and ADMINS can do this. If I do not see the MCP tile
    at all, I am a plain member and need an owner or admin to do it for me.
  - MCP requires the Unlimited plan. If the tile is greyed out with a padlock
    reading UNLIMITED, I am on a lower plan and need to upgrade first.

Never print my key back to me in full, never paste it into a public place, and
never commit it to a repository.

THE SERVER

  URL:       https://app.truemetriks.com/mcp
  Transport: Streamable HTTP (POST)
  Auth:      Authorization: Bearer <MY_MCP_KEY>

THE TWO CONFIGS, WHICH ARE NOT INTERCHANGEABLE

Claude Desktop is stdio only. It has no field for a bearer header, so it needs
the npx mcp-remote bridge. Its config file is claude_desktop_config.json:
  macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
  Windows: %APPDATA%\Claude\claude_desktop_config.json
Give it EXACTLY this, with my key in place of YOUR_MCP_KEY:

{
  "mcpServers": {
    "truemetriks": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.truemetriks.com/mcp",
        "--header",
        "Authorization: Bearer YOUR_MCP_KEY"
      ]
    }
  }
}

Cursor, Claude Code and other remote-capable clients take the url and headers
directly and must NOT be given the bridge form. Give them EXACTLY this:

{
  "mcpServers": {
    "truemetriks": {
      "url": "https://app.truemetriks.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_KEY"
      }
    }
  }
}

  Cursor keeps this in ~/.cursor/mcp.json, or .cursor/mcp.json inside a project.
  Claude Code keeps it in .mcp.json in the project root.

Tell me to restart the client after saving the config.

THE 14 TOOLS AND HOW TO CALL THEM

Once connected you will also receive these from the server, but here they are
so you know what is available before we start, and can pick the right one.

Every tool takes start_date and end_date as YYYY-MM-DD strings, EXCEPT
get_buyer_detail and compare_periods. NO tool takes a site or organization
parameter: the key is bound to one site, so never ask me which site I mean and
never invent such an argument. Optional arguments are marked.

  get_overview(start_date, end_date)
    Sessions, pageviews, unique users, bounce rate, session duration.
  get_channel_breakdown(start_date, end_date, traffic?)
    By marketing ecosystem (facebook, google, tiktok, email, direct): visits,
    visitors, revenue, ad spend, ROAS. traffic is "all" (default), "paid" or
    "organic". Purchases attribute to the earliest touch inside the range.
  get_campaign_performance(start_date, end_date)
    Per campaign: visits, revenue, spend, ROAS, cost per sale. Use for best
    and worst performing campaigns.
  get_ad_spend(start_date, end_date, group_by?)
    Spend from synced ad accounts. group_by is "platform" (default) or
    "campaign". Top 100 rows; check the truncated flag.
  get_revenue_summary(start_date, end_date)
    Revenue, purchases, average order value, conversion rate, LTV. This is the
    ATTRIBUTED view and matches the dashboard exactly, so use it for headline
    revenue and for any LTV figure I might compare against the dashboard.
  get_product_performance(start_date, end_date)
    Per product: revenue, orders, average order value.
  get_customer_ltv(start_date, end_date)
    Per-buyer spend distribution: average and median LTV, repeat rate. Counted
    straight from Purchase events with NO attribution scoping, so it can
    differ from get_revenue_summary. Do not present the two as the same
    metric.
  get_buyer_journeys(start_date, end_date, limit?)
    Per-buyer lifetime attribution: first touch, last touch, sessions,
    revenue, days to purchase. limit is 1-100, default 20.
  get_buyer_detail(buyer_id)
    Full event timeline for ONE buyer. buyer_id is an email or visitor id as
    returned by get_buyer_journeys. Takes NO dates. Capped at 500 events.
  get_time_to_purchase(start_date, end_date)
    First visit to first purchase: buyer count, average and median days.
  get_event_funnel(start_date, end_date, from_event, to_event?)
    Event-to-event conversion per person, with average and median hours
    between. from_event is REQUIRED, for example "Lead" or "Schedule".
    to_event defaults to "Purchase".
  get_funnel_ab_results(start_date, end_date, funnel_id?)
    Saved funnels including A/B variant splits. Call WITHOUT funnel_id first
    to list the saved funnels, then again with the id you want.
  get_traffic_dimensions(start_date, end_date, dimension)
    Top pages or referrers. dimension is REQUIRED: "pathname" or "referrer".
    Top 25 only; check the truncated flag.
  compare_periods(tool, period_a_start, period_a_end, period_b_start,
                  period_b_end)
    Runs another tool over two ranges and returns both. tool is the NAME of
    one of the tools above, for example "get_revenue_summary". Use this for
    any this-versus-that question rather than calling a tool twice yourself.

Resolve relative dates like "last week" into real YYYY-MM-DD values before
calling, and tell me the exact range you used so I can check it.

Good first questions to suggest to me:
  - How much revenue did I make last week, and which channel drove it?
  - What is my best performing campaign by ROAS this month?
  - How long do buyers take from first visit to first purchase?
  - Compare this month with last month.

LIMITS TO KNOW

  - One request may span at most 180 days. Longer ranges are refused, so split
    them into shorter periods.
  - 30 requests per minute and 2000 per day per key, with at most 3 running at
    once.
  - Everything is read-only. Nothing my AI does can change my data.

IF IT DOES NOT WORK

  401  the key is wrong, revoked, or is a plain API key rather than an MCP key.
  403  TIER_NO_MCP means the workspace is not on the Unlimited plan.
  429  too many requests, wait and retry.
  Tell me to restart the AI client after any config change, because most
  clients only read their MCP config at startup.