# 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 or the Query API. A person approves once in their browser; you get the site, its snippet, a secret key and the MCP config.

## Given a code

If the person pasted a prompt from nanolytics with a `device_code`, they approved it there: skip steps 1 to 3. The prompt's one call saved the result to the file its `curl -o` names; go on at step 4 with that file as `$RESULT`. If the file's `error` is `expired_token` or `invalid_grant`, the code is spent: ask them for a new prompt, or start at step 1.

## 1. Ask for a connect link

```sh
curl -s -X POST https://app.nanolytics.dev/api/connect -H 'content-type: application/json' \
  -d '{"domain":"example.com","timezone":"Europe/Athens","client":"Claude Code"}'
```

- `domain`: the site's production hostname. It becomes the one host the tracker may report from.
- `timezone`: an IANA name, the machine's or the site's; days start at midnight there. UTC by default.
- `client`: your name. The person sees it, and it names the key.

The answer is RFC 8628's: `device_code` (keep it to yourself), `user_code`, `verification_uri_complete`, `expires_in` (900 s) and `interval` (5 s). Nothing is created yet.

## 2. Give the person the link

Show `verification_uri_complete` and `user_code`, and ask them to approve. They sign in or sign up, check that the code matches yours, and pick the organization.

## 3. Poll until they decide

```sh
RESULT="${TMPDIR:-/tmp}/nanolytics-$USER_CODE.json"
curl -s -X POST https://app.nanolytics.dev/api/connect/token -o "$RESULT" \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code -d device_code=$DEVICE_CODE
jq -r '.error // "ready"' "$RESULT"
```

The result holds a secret key, so it goes to a file, named by your request, and never to the screen. One call every `interval` seconds; each answers at once, so run it in a loop of short calls, not one that waits. While there's no result, the file's `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.

`ready` is the result, handed out once: keep the file until step 4 is done. If the domain is already one of the organization's sites, it is that site with a new key, not a second site.

## 4. Put each piece where it goes

The result in `$RESULT` holds the site's secret key, `access_token`. Keep it out of the transcript and the repository: never print it (`jq 'del(.access_token)' "$RESULT"` shows the rest), save it before anything else, and make the repository's own `.gitignore` cover `.env.local`:

```sh
echo "NANOLYTICS_KEY=$(jq -r .access_token "$RESULT")" >> .env.local
git -c core.excludesFile=/dev/null check-ignore -q .env.local || printf '\n.env.local\n' >> .gitignore
```

- `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.
- MCP: run `mcp.claude_code` in Claude Code. It reads the key from `.env.local` and keeps the server for this project on this machine, not in the repository; its tools appear in the next session. Other clients take `mcp.config`, which reads `${NANOLYTICS_KEY}` from the environment.

## 5. Check it before deploying

Run `check.hit`, then `check.health`, from the project's root. The hit is one test pageview as if from a dev server, sent without a browser or a change to the project; it answers 202. Within 10 seconds the health lists it under `host_not_allowed` with `localhost` as the sample, and nothing is counted: the site, its public key and the endpoint work. A new key also takes up to 10 seconds: if the health answers `unauthorized`, wait and run it again.

Then delete `$RESULT`. After the deploy, the MCP tool `install_status` shows the first real hit, and the dashboard (`site.dashboard`) the visit within seconds.

## Already signed in to MCP

With an OAuth session, `create_site` makes the site (or returns the one the organization has for that domain) and its snippet, `install_status` checks it, and `create_key` makes a key for server-side events.

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