# MCP server

The MCP server lets your coding agent answer questions about your analytics. It uses the same Query API as the dashboard, so your agent gets the same numbers you see. This page shows how to connect a client, how it authenticates, and which tools it can use.

## Endpoint

- The server is at `https://app.nanolytics.dev/mcp` and uses Streamable HTTP.
- It's stateless: each request is handled on its own.
- Every response includes a `query_id` and an `as_of`. Your agent should cite them alongside the numbers it gives you.

## Authentication

A client can connect in one of two ways.

| | OAuth | A site's secret key |
|---|---|---|
| How it works | The client opens a browser, and you sign in and choose the organization | The client sends `Authorization: Bearer sk_…` with every request |
| Access | Every site in your organization | That one site |
| Tools | All of them | All except `create_site` and `create_key` |
| Best for | Working across sites, or adding new ones | An agent that installed nanolytics on one project (see [Install](/docs/install)) |

The OAuth server's metadata is at `https://app.nanolytics.dev/.well-known/oauth-protected-resource/mcp`. Clients that support MCP's OAuth find it automatically.

You can get a secret key from the connect flow, from **Settings → API keys**, or with the `create_key` tool. Keep it out of your repository: it can read and write the site's data until you revoke it.

## Claude Code

To connect with OAuth:

```sh
claude mcp add --transport http nanolytics https://app.nanolytics.dev/mcp
```

To connect with a site's secret key, read it from `.env.local` so the key never appears in the command:

```sh
claude mcp add --transport http --scope local nanolytics https://app.nanolytics.dev/mcp --header "Authorization: Bearer $(grep '^NANOLYTICS_KEY=' .env.local | cut -d= -f2-)"
```

`--scope local` keeps the server configured for this project on your machine only, so it isn't committed to the repository. The tools are available from your next session.

## Other clients

For clients that take an `mcpServers` entry and read the key from the environment, use this config and set `NANOLYTICS_KEY` to the site's secret key:

```json
{
  "mcpServers": {
    "nanolytics": {
      "type": "http",
      "url": "https://app.nanolytics.dev/mcp",
      "headers": { "Authorization": "Bearer ${NANOLYTICS_KEY}" }
    }
  }
}
```

If your client supports MCP's OAuth, all it needs is the URL: `https://app.nanolytics.dev/mcp`.

## Typical workflow

1. Call `list_sites` to get the sites you can read, with each one's ID, domain and timezone.
2. Call `get_schema` for a site to see its first day of data, its dimensions, metrics and goals, and its event names with their property keys. Your agent should read this before writing a query.
3. Ask with `query`. For ordered steps use `funnel`, for where people went from a step use `paths`, for one error group use `error`, and for recorded sessions use `replays` and `replay`.

To install on a new site, call `create_site`, add its snippet to your pages, then check it with `install_status`. To track more (page speed, errors, session replay, outbound links), use `update_site`. After the first line of code, neither needs any further code change.

## Tools

| Tool | Description |
|---|---|
| `list_sites` | The sites you can read: each one's ID, domain and timezone. |
| `get_schema` | What a site has to ask about: its first day with data and today (in the site's timezone), the dimensions with their cardinalities, the metrics, its goals, and the event names with each one's property keys and how many values each takes. |
| `query` | Runs a query on the site's analytics through the public Query API, the same one the dashboard uses. |
| `funnel` | Of the visitors who did the first step, how many then did each next step, in order, within a window of the first, and how soon (the median time from step 1). |
| `paths` | From one step, where people went next (direction after), a few steps deep, or how they arrived at it (before). |
| `error` | One error group in a range: where it is thrown (call sites: each occurrence's top frame on the site's own host, by occurrences), in which releases, and its latest 10 occurrences with their page, browser, release, message as sent and stack frames. |
| `replays` | Recorded sessions (session replay), newest first, when the schema's has_replays is true: each one's start_ms (epoch milliseconds), duration_ms (how long its replay runs), pages (its pages in order, at most 20), pageviews, country, browser, os, device, errors (occurrences), replay (a link to watch it in the dashboard), and recording and date for the replay tool, which reads what happened in it. |
| `replay` | What happened in one recorded session, without watching it: the session as replays lists it, where it came from (source, channel, referrer_host), and its events in order (up to 1,000), each at_ms after the session started. |
| `create_site` | Adds a site to your organization, or returns the one it already has for that domain: its ID, the snippet to put in every page's <head>, and how to check the install before deploying. Signed in with OAuth only. |
| `install_status` | Whether a site's tracker is reporting: the first and last hit (bots included, since a headless browser's hits are stored as a bot's), pageviews today, hits dropped in the last hour by reason, and what the tracker collects (update_site changes it). |
| `update_site` | Changes what a site's tracker collects, with no change to its tag or any code: the site's script carries its settings, and visitors get a change within five minutes. |
| `create_key` | Makes a secret API key for a site, for the Events API (server-side events) or the Query API, and returns it once: only its hash is kept. Signed in with OAuth only. |
| `create_goal` | Adds a goal: a named predicate over a custom event's name or a page path (* matches any run of characters, as /blog/*). |
| `delete_goal` | Removes a goal by name. |

## Example questions

| Question | Tool |
|---|---|
| What changed this month? | `query` with `"compare": "previous"` |
| Where do visitors come from? | `query` with a breakdown by `source` |
| Which pages are slow on phones? | `query` with `lcp_p75` by `route`, filtered on `device` |
| What broke since the last deploy? | `query` with `errors` by `error_group`, ordered by `first`, then `error` for one group |
| How many people who saw pricing signed up within a day? | `funnel` with a page step and an event step, `"window": "1d"` |
| Where do people go after the docs? | `paths` with `at` on the page |
| Show me sessions that hit an error | `replays` with a filter on `error_group`, then `replay` for one |
| Is the script working? | `install_status` |
| Turn on page speed | `update_site` with `vitals` on |
| Count signups as a goal | `create_goal` with `event_name` |

Goals apply to all the data you've already collected. Settings you change with `update_site` reach visitors within five minutes.

## Same numbers as the dashboard

The dashboard and the [Query API](/docs/api) use the same engine, so a number from MCP matches the dashboard for the same range and filters.
