# SnowAnalytics for agents: signing in

SnowAnalytics is privacy-friendly web analytics with session replays, error tracking, visitor feedback and revenue attribution. Agents use it through its MCP server:

    https://mcp.snowanalytics.app/mcp

Every tool acts as one person, on every site they can open. Docs: https://snowanalytics.app/docs/mcp

## With a person at a browser (recommended)

Add the MCP server to your client (for Claude Code: `claude mcp add --transport http snowanalytics https://mcp.snowanalytics.app/mcp`). It answers 401 with OAuth metadata, and the client opens SnowAnalytics' sign-in in the browser. Someone without an account can choose **Start without an account**: you get a guest workspace now, and they save it to an account later.

## Without a browser: start a guest

    POST https://snowanalytics.app/api/agent/start
    Content-Type: application/json

    {"agent": "<your name, e.g. Claude Code>"}

It answers 201 with `agentKey`, `mcpUrl`, `workspaceId`, `claimUrl` and `next`.

- Send `Authorization: Bearer <agentKey>` to the MCP server (Claude Code: `claude mcp add --transport http snowanalytics https://mcp.snowanalytics.app/mcp --header "Authorization: Bearer <agentKey>"`). The key is a secret: keep it in a git-ignored env file, never in code.
- Show the person `claimUrl`. Opening it and signing in or up saves the guest's sites to their account; saving ends the guest key, so reconnect with OAuth after.
- Until it's saved, a guest has at most 2 sites and can't connect payment or ad accounts, add alert destinations, invite people, make keys or pay. Unsaved guests are deleted a month after their trial's counting stops.
- An address can start 3 guests a day.

## With an account but no browser (CI, cloud agents)

The person makes an agent key in SnowAnalytics → Account → Connected apps (https://snowanalytics.app/account/apps) and you send it as a bearer token.

## From a shell: the CLI

The SnowAnalytics CLI runs the same tools as commands, for agents that work in a terminal. Its output is JSON when another program reads it, and `--help` on any command lists its options.

    npx @kapybara/snowanalytics login            # the person signs in through their browser
    npx @kapybara/snowanalytics login --guest    # or start without an account; it prints the link that saves it
    npx @kapybara/snowanalytics errors           # then read: sites, overview, errors, feedback, sessions…

With an agent key, set `SNOWANALYTICS_AGENT_KEY` instead of signing in. Docs: https://snowanalytics.app/docs/cli
