# Instructions for agents

Use this page when you are setting up Tinylytics for a human. They own the account. You start the 14-day trial. They set a password in a browser. Then you connect over [MCP](/docs/mcp).

Do not fill the [sign-up form](/auth/sign_up). Do not invent a password. Do not collect a card. The signup API never returns an API key.

<span id="start"></span>
## 1. Start the trial

`POST https://tinylytics.app/api/v1/agent_signups` with the owner's email and `tos_accepted: true`.

```bash
curl -X POST "https://tinylytics.app/api/v1/agent_signups" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "owner@example.com",
    "agent_name": "Grok",
    "agent_client": "grok",
    "tos_accepted": true
  }'
```

A `201` response includes `owner_activation_url`, `status_url`, `mcp_url`, and a 14-day Pro trial. `site_url` is optional. It does not create a site.

If the email already has an account, you get `existing_account` and no activation URL. Ask the owner to sign in and connect MCP.

<span id="hand-off"></span>
## 2. Hand them the activation link

Give the owner `owner_activation_url`. They open it in a browser, choose a password, and activate. You wait. Do not fill that form yourself.

Tinylytics also emails them the same link.

<span id="poll"></span>
## 3. Poll until they activate

`GET` `status_url` every 15 seconds. Cap that at about 15 minutes, then back off. Send the token as `X-Agent-Signup-Token`. `?token=` also works, but the header stays out of access logs.

```bash
curl "https://tinylytics.app/api/v1/agent_signups/ags_…" \
  -H "Accept: application/json" \
  -H "X-Agent-Signup-Token: …"
```

| Status | What you do |
|--------|-------------|
| `pending_owner` | Keep waiting. Remind the owner about the link if needed. |
| `owner_activated` | Connect MCP. |
| `mcp_connected` | You are in. Create or list sites. |
| `expired` | Call `POST /api/v1/agent_signups` again. The new `owner_activation_url` is in the JSON, not a new email. |
| `existing_account` | Ask them to sign in and connect MCP. |

Polling never returns an API key, a password, or `token_digest`. Unknown id or a bad token returns `404`.

<span id="connect"></span>
## 4. Connect over MCP

When `status` is `owner_activated`:

```bash
grok mcp add --transport http tinylytics https://tinylytics.app/mcp
```

That writes `~/.grok/config.toml`. It does not sign in.

The owner authenticates in Grok. They run `/mcps`, select tinylytics, and press `i`. They sign in and pick Full access if you need to create a site. Read only cannot `create_site`.

Then reload this session (`/mcps`, then `r`) or start a new session. Do that before calling `get_me` or `create_site`. Tinylytics can report `mcp_connected` while this turn still has no tools.

For other clients, paste `https://tinylytics.app/mcp` into Claude, Cursor, ChatGPT, or Grok connectors. The owner signs in and picks access. That session shows up under Account → Connections.

If the client only supports a static header, ask the owner to create a key under Account → API Access and paste `Authorization: Bearer tly-ro-…` (or `tly-fa-…`).

<span id="prove"></span>
## 5. Prove access, then add the site

After the reload, call `GET /api/v1/me` or MCP `get_me`. Send a User-Agent on HTTP API calls. Cloudflare returns 1010 without one.

Then create or list sites. Do not assume a site exists because you omitted or sent `site_url`.

More after connect: [MCP](/docs/mcp) and [API](/docs/api).