# Set up Pickrate

You are an AI coding agent. These are the official setup instructions from **Pickrate** (https://pickrate.io) — analytics for the AI agents that visit a website. **Do the steps yourself**; don't just explain them to the user. The only thing you need from the user is their Pickrate secret key.

What you're installing: a tiny server-side collector that reports which AI agents (GPTBot, ClaudeBot, Perplexity, and the rest) crawl and read this site — plus an MCP connection so the user can later just ask you things like "how much traffic are agents driving?" or "how many signups have agents sent me?". It works server-side because agents don't run JavaScript, so normal web analytics can't see them.

## 1. Detect the stack

Inspect the project. Is it **Next.js** (a `next` dependency)? Another Node/edge server? Or a **static / no-code host** (Webflow, Wix, Shopify, Framer) with no server the user controls?

## 2. Install the collector

**Next.js:**
- Run `npm install @pickrate/collector`.
- If there is **no** middleware file, create `middleware.ts` at the project root (or in `src/`):
  ```ts
  export { middleware } from "@pickrate/collector/next";
  export const config = { matcher: ["/((?!_next|favicon).*)"] };
  ```
- If a middleware file **already exists**, do NOT overwrite it. Compose inside it:
  ```ts
  import { createCollector } from "@pickrate/collector";
  const pickrate = createCollector({ key: process.env.PICKRATE_KEY });
  // in the middleware function, before it returns (ev is the NextFetchEvent):
  ev?.waitUntil?.(pickrate.report({
    method: req.method,
    path: req.nextUrl.pathname,
    userAgent: req.headers.get("user-agent") ?? "",
  }));
  ```
- Add `PICKRATE_KEY=` to `.env.local` (leave the value blank until step 3).

**Not Next.js, or a no-code / static host:** run a Cloudflare Worker in front of the site (it also captures response status, so "gaps" work):
```js
import collector from "@pickrate/collector/worker";
export default collector; // set PICKRATE_KEY as a Worker secret
```
Or POST `agent_interaction` events straight to `https://pickrate.io/api/collect`. See https://pickrate.io/agent-setup.

## 3. Ask the user for their secret key

Say exactly: **"Generate a secret key at https://pickrate.io/dashboard/settings → Connect your agent → Generate secret key, then paste it here."**
Put the value into `PICKRATE_KEY` (env var / Worker secret). It must stay server-side — never put it in client code.

## 4. Connect Pickrate to the agent (MCP)

If you are **Claude Code**, run:
```
claude mcp add --transport http pickrate https://pickrate.io/api/mcp --header "Authorization: Bearer <the key the user gave you>"
```
Other agents: add a remote (Streamable HTTP) MCP server at `https://pickrate.io/api/mcp` with header `Authorization: Bearer <the key>`.

## 5. Verify the pipe actually works

A wrong or stale key fails **silently** — the collector never throws — so DON'T assume it works. After the user deploys:
- Seed a hit: `curl -A "ClaudeBot/1.0" https://<their-site>/` (any real content path).
- Check the site's server logs (e.g. `vercel logs`). If you see a `[pickrate] collector: 401` warning, the key is wrong/stale — fix `PICKRATE_KEY` and redeploy.
- No warning, and the hit appears on their Pickrate Agents dashboard (or via getMyAgents) = it's working.

Only then confirm:
- ✅ **Collector installed and verified** — agent hits are reaching Pickrate.
- ✅ **Agent connected** — they can ask you things like *"how many signups have agents sent me?"* and you'll answer from their live data (Pickrate's `getMyAgents` tool).

## Rules

- Make the edits yourself; don't hand the user a checklist.
- Never place the secret key in client-side code — server/env only.
- Use only the install methods above; don't invent alternatives.
- Docs: https://pickrate.io/agent-setup