query:read) and dashboard changes (dashboards:write) are separate scopes.
Create an API key
You need the owner or admin role and a verified MFA session.- Open your project and go to Settings, then Integrations.
- Under API keys, enter a New key name.
- Choose the Scopes (see below). The four read scopes (Analytics, Dashboards, Attribution and Profiles) are selected when the form opens. SQL, Dashboard changes and Profile properties are not selected. A key needs at least one scope.
- Click Create API key, then copy the key. It starts with
ua_api_and is shown only once. Older keys that start withua_mcp_keep working.
Scopes
The server registers only the tools that a key’s scopes allow. Give each integration the smallest set of scopes it needs. Each scope is explicit, and no scope includes another: a key with
dashboards:write and without dashboards:read can change dashboards, but it cannot list or read them. A call to a tool without its scope returns an error that names the missing scope.
A key with query:read or dashboards:write acts for the person who created it, and the audit log shows its changes as that person (via: mcp). The key stops working when that person leaves the workspace, and it keeps only its read scopes when their role goes below editor.
Tools
Every tool returns structured content. Read tools are marked read-only; tools that change or delete data are marked destructive. See Charts and dashboards for the chart spec and examples.
Report totals
get_analytics returns three fields with the rows:
The server calculates
totals, so the AI client does not add rows:
pageviews,custom_events,revenueandsessionsare the sums of all days, also the days that are not inrows.visitorsis the number of unique visitors in the date range. It is not the sum of the daily values: a visitor who comes on two days is one visitor.
totals:
kpisreturns one row, and that row is the totals for the date range.top_pages,top_sourcesandtop_eventsreturn the first 20 groups only. A visitor can be in more than one group, so the rows do not add up to a total. For a total, callkpiswith the same dates and filters.
Sessions
kpis and event_timeseries return the session metrics of the Overview. See Metrics for the definitions.
- A session counts on the UTC day of its first event. So the daily
sessionsadd up to thekpisvalue, andtotals.sessionsis that sum. - With a filter, the result has this sentence in
notes: “Sessions, bounce rate and session duration count all activity of the visitors that match the filter.” The other columns count only the events that match. - With a filter on the field
eventor on an event property (properties.<key>), the session columns are absent, andnoteshas this sentence: “Sessions are not shown with an event filter.” The session report would count all sessions of the visitors that sent the event, not the sessions that contain it. - No report returns sessions by a dimension.
top_sources,top_pagesandtop_eventshave no session count. Useexecute_queryfor that. - If the session read fails, the tool call fails.
Connect a client
The server uses Streamable HTTP athttps://YOUR_COLLECTOR_ENDPOINT/mcp. Send the key as a bearer token:
- Claude Code
- Cursor
- Claude Desktop
Clients that support OAuth, such as Claude and ChatGPT, can connect without a key when OAuth is enabled. See MCP OAuth. The endpoint refuses requests that carry a browser
Origin header, so call it from an MCP client, not from a web page.Example prompts
- “What were my top 10 pages last week?”
- “Which channels brought the most visitors in October?”
- “Which UTM campaigns get credit for
signup_completedwith the linear model?” - “Show me the profile and traits of user
user_123.” - “Create a dashboard called Launch with daily page views and visitors as a combo chart, and a goal line at 500.”
- “Preview a scatter of page views against events per visitor for last week.”
Limits
An exhausted budget returns
429 with Retry-After: 60.
Security
- Keys are stored as SHA-256 hashes, with a short display prefix.
- A key reads only its own project. A tool cannot choose another project.
- Error messages do not include internal database or network details.
- Key creation is written to the audit log, with the granted scopes. Dashboard changes and SQL runs through a key are audited as its creator, with
via: mcp.