# Install nanolytics

> For coding agents. nanolytics is web and product analytics. Install it on the site you work on, then ask about its traffic through MCP. A person approves once in their browser; you get the site, its snippet and MCP's URL. Nothing in it is secret.

## 1. Ask for a connect link

```sh
TZ_NAME=$(readlink /etc/localtime | sed 's#.*/zoneinfo/##')
curl -s -X POST https://app.nanolytics.dev/api/connect -H 'content-type: application/json' \
  -d "{\"domain\":\"example.com\",\"timezone\":\"$TZ_NAME\",\"client\":\"Claude Code\"}"
```

- `domain`: the site's production hostname. It becomes the one host the tracker may report from.
- `timezone`: the machine's IANA name, as the first line reads it, or the site's if you know it; days start at midnight there. Without it, the timezone of the person who approves.
- `client`: your name. The person sees it when approving.

The answer is RFC 8628's: `device_code` (keep it to yourself: whoever holds it collects the result), `user_code`, `verification_uri_complete`, `expires_in` (900 s) and `interval` (5 s), and `show`, the sentence for the person. Nothing is created yet.

## 2. Tell the person the link, in your reply

Before you poll, open `verification_uri_complete` in the person's browser (`open` on macOS, `xdg-open` on Linux) and write `show` to them in your reply, word for word: they can't approve a link they haven't seen, and a command's output may never reach them. They sign in or sign up, check the code and pick the organization. Then poll (step 3), or end your turn and poll once they say they've approved.

## 3. Poll until they decide

```sh
curl -s -X POST https://app.nanolytics.dev/api/connect/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code -d device_code=$DEVICE_CODE
```

One call every `interval` seconds; each answers at once, so run it in a loop of short calls, not one that waits. Until there's a result, its `error`:

- `authorization_pending`: not yet; ask again after `interval`.
- `slow_down`: add 5 seconds to `interval`.
- `access_denied`: the person said no. Stop.
- `expired_token`: nobody approved within 15 minutes. Start again at step 1.
- `invalid_grant`: no such request, or its result was already handed out. Start again at step 1.

Otherwise it's the result, handed out once. If the domain is already one of the organization's sites, it is that site, not a second one.

## 4. Put each piece where it goes

- `snippet.html` in the `<head>` of every page (`index.html` for Vite), or `snippet.nextjs` inside `<body>` in Next.js's `app/layout.tsx`. It holds only the site's public key, so commit it. It is the whole install: to collect page speed, errors, session replay or outbound links, use MCP's `update_site`, not the tag.
- MCP: run `mcp.claude_code` in Claude Code; other clients take `mcp.config`. There is no key: on first use the client opens the browser and the person signs in, and the client keeps the token. Its tools appear in the next session.

## 5. Check it before deploying

Run `check.hit` from the project's root. It sends one test pageview as if from a dev server, without a browser or a change to the project, and answers 202. It is dropped as `host_not_allowed`, never counted, and the person sees it arrive on the page where they approved. From the next session, MCP's `install_status` shows it too.

After the deploy, the dashboard (`site.dashboard`) shows the first visit within seconds.

## Already signed in to MCP

`create_site` makes the site (or returns the one the organization has for that domain) and its snippet, and `install_status` checks it. Code that calls the Query or Events API needs a secret key: the person makes one in Settings, or `create_key` does; keep it in a git-ignored file and never print it.

## Then

- [llms.txt](https://app.nanolytics.dev/llms.txt): the MCP tools and the Query API, with examples.
- [llms-full.txt](https://app.nanolytics.dev/llms-full.txt): all of it, with the OpenAPI spec inline.
