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.

Do not fill the sign-up form. Do not invent a password. Do not collect a card. The signup API never returns an API key.

1. Start the trial

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

curl -X POST "https://tinylytics.app/api/v1/agent_signups" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "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.

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.

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.

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.

4. Connect over MCP

When status is owner_activated:

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-…).

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.