> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect Claude, Cursor and other AI tools to your analytics with a project-scoped MCP server: reports, SQL, and dashboard charts.

The ManaLens **MCP server** lets AI tools that support the [Model Context Protocol](https://modelcontextprotocol.io) use your analytics. Ask Claude, Cursor or another MCP client about your traffic, campaigns, conversions and users, or let it build dashboard charts.

You connect with an [API key](https://docs.manalens.dev/api/authentication.md#api-keys). Each key works on one project only. A key has only the scopes that you choose, and it needs at least one. SQL (`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](https://docs.manalens.dev/security/mfa.md) session.

1. Open your project and go to **Settings**, then **Integrations**.
2. Under **API keys**, enter a **New key name**.
3. 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.
4. Click **Create API key**, then copy the key. It starts with `ua_api_` and is shown **only once**. Older keys that start with `ua_mcp_` keep working.

Click **Revoke** to disable a key at once.

## Scopes

| Scope | Label | Tools |
| - | - | - |
| `analytics:read` | Analytics: read aggregate analytics reports and the data schema | `get_analytics`, `describe_schema` |
| `dashboards:read` | Dashboards: list and read saved dashboards and charts | `list_dashboards`, `get_dashboard`, `list_charts`, `get_chart` |
| `attribution:read` | Attribution: read conversion and revenue attribution | `get_attribution` |
| `profiles:read` | Profiles: read identified user profiles and traits | `get_profile` |
| `query:read` | SQL: run SQL on raw events and preview charts | `execute_query`, `preview_chart` |
| `dashboards:write` | Dashboard changes: create, edit, move and delete dashboards and charts. It does not include reading them. | `create_dashboard`, `update_dashboard`, `delete_dashboard`, `create_chart`, `update_chart`, `delete_chart`, `duplicate_chart`, `move_chart`, `reorder_charts` |
| `profiles:write` | Profile properties: set and delete them through the REST API | None. Used by [`PUT .../profiles/:userId/properties`](https://docs.manalens.dev/api/profiles/update-properties). Keys only. |

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

| Tool | Description |
| - | - |
| `get_analytics` | Reads an aggregate report: `kpis`, `event_timeseries`, `top_pages`, `top_sources` or `top_events`. Takes a date range and filters (page path, UTM fields, paid source, channel, click ID, device, country, and up to 20 operator filters, including event properties). Returns up to 100 rows, with `row_count`, `truncated` and, for `event_timeseries`, `totals`. `kpis` and `event_timeseries` also return [sessions](#sessions). See [Report totals](#report-totals). |
| `get_attribution` | Gives conversion and revenue credit with an [attribution model](https://docs.manalens.dev/attribution/models.md). Takes the conversion event, model, grouping, dates, lookback and half-life. |
| `list_dashboards` | Lists the project's saved dashboards |
| `get_profile` | Reads an identified user's profile and traits by `user_id` |
| `list_dashboards` | Lists the project's dashboards with their chart counts |
| `get_dashboard`, `list_charts`, `get_chart` | Read a dashboard and its charts, each with its chart spec. The charts do not run. |
| `describe_schema` | The `raw_events` columns, context keys, SQL rules and one example chart spec per view feature |
| `execute_query` | Runs one SQL query on `raw_events` (the [Explorer](https://docs.manalens.dev/features/explorer.md) rules) and returns up to 200 rows |
| `preview_chart` | Runs a chart spec and returns the rows with the spec. Draws the chart in clients that support MCP Apps. |
| `create_dashboard`, `update_dashboard`, `delete_dashboard` | Create, rename or delete a dashboard. Delete needs `"confirm": true`. |
| `create_chart`, `update_chart` | Save a chart spec on a dashboard, or replace one. The spec is checked as in the dashboard editor; nothing is saved on a refusal. |
| `delete_chart`, `duplicate_chart`, `move_chart`, `reorder_charts` | Delete (with `"confirm": true`), copy, move to another dashboard, or reorder charts |

Every tool returns structured content. Read tools are marked read-only; tools that change or delete data are marked destructive. See [Charts and dashboards](https://docs.manalens.dev/mcp/charts.md) for the chart spec and examples.

### Report totals

`get_analytics` returns three fields with the rows:

| Field | Meaning |
| - | - |
| `row_count` | The number of rows that the report returned |
| `truncated` | `true` when `rows` has only the first 100 of `row_count`. A daily series longer than 100 days is cut. |
| `totals` | Totals for the full date range. Only `event_timeseries` has this field. |
| `notes` | Fixed sentences on how to read the session columns. The field is absent when there is no note. |

The server calculates `totals`, so the AI client does not add rows:

* `pageviews`, `custom_events`, `revenue` and `sessions` are the sums of all days, also the days that are not in `rows`.
* `visitors` is 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.

The other reports have no `totals`:

* `kpis` returns one row, and that row is the totals for the date range.
* `top_pages`, `top_sources` and `top_events` return 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, call `kpis` with the same dates and filters.

### Sessions

`kpis` and `event_timeseries` return the session metrics of the [Overview](https://docs.manalens.dev/features/overview.md). See [Metrics](https://docs.manalens.dev/data/metrics.md#sessions) for the definitions.

| Report | Columns |
| - | - |
| `kpis` | `sessions`, `bounce_rate` (a percent, 0 to 100) and `session_duration_sec` (the average seconds from the first to the last event of a session), for the date range |
| `event_timeseries` | `sessions` for each day. A day with no session has 0. |

* A session counts on the UTC day of its first event. So the daily `sessions` add up to the `kpis` value, and `totals.sessions` is 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 `event` or on an event property (`properties.<key>`), the session columns are absent, and `notes` has 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_pages` and `top_events` have no session count. Use `execute_query` for that.
* If the session read fails, the tool call fails.

## Connect a client

The server uses Streamable HTTP at `https://YOUR_COLLECTOR_ENDPOINT/mcp`. Send the key as a bearer token:

```
Authorization: Bearer ua_api_...
```

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http untitled-analytics https://YOUR_COLLECTOR_ENDPOINT/mcp \
>   --header "Authorization: Bearer ua_api_..."
> ```

> [tab] Cursor
>
> Add this to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "untitled-analytics": {
>       "url": "https://YOUR_COLLECTOR_ENDPOINT/mcp",
>       "headers": { "Authorization": "Bearer ua_api_..." }
>     }
>   }
> }
> ```

> [tab] Claude Desktop
>
> In Claude Desktop, go to **Settings**, **Developer**, **Edit Config**. Use the `mcp-remote` bridge to add the header:
>
> ```json claude_desktop_config.json theme={null}
> {
>   "mcpServers": {
>     "untitled-analytics": {
>       "command": "npx",
>       "args": [
>         "mcp-remote",
>         "https://YOUR_COLLECTOR_ENDPOINT/mcp",
>         "--header",
>         "Authorization: Bearer ua_api_..."
>       ]
>     }
>   }
> }
> ```
>
> Restart Claude Desktop to load the server.

> [!NOTE]
>
> Clients that support OAuth, such as Claude and ChatGPT, can connect without a key when OAuth is enabled. See [MCP OAuth](https://docs.manalens.dev/mcp/oauth.md). 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_completed` with 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

| Budget | Limit |
| - | - |
| Per key | 120 requests per minute |
| Per workspace | 600 requests per minute, shared by every key in the workspace |
| `execute_query` | The Explorer budgets: 10 per minute per person, 30 per project |
| `preview_chart` | 60 per minute per person, 240 per project |
| `create_chart`, `update_chart` with SQL | 30 SQL charts per minute per person |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.