@mentionflow/vercel

AI crawlers visit your site every day and your analytics never sees them. GPTBot, ClaudeBot, PerplexityBot and the rest don't run JavaScript, so GA, GTM and every client-side snippet are blind to them.

This package catches them where they can't hide: in your Next.js proxy/middleware, server-side. Every hit shows up in MentionFlow → Agent analytics. You don't need Cloudflare, log drains, or any paid Vercel feature. It works on every Vercel plan and anywhere else Next.js runs (self-hosted Node, Docker), on both the Edge and Node.js runtimes.

It never touches your traffic. The report fires after a user-agent check, while your response is already on its way. No request is blocked, delayed, or failed because of this package, even if MentionFlow is unreachable. Zero dependencies.

Setup in 3 steps

1. Install:

npm install @mentionflow/vercel

2. Add one file. Next.js 16+ uses proxy.ts at the project root (or in src/):

// proxy.ts
import { withMentionFlow } from "@mentionflow/vercel";

export default withMentionFlow();

// already have a proxy? wrap it. its behavior stays untouched:
// export default withMentionFlow(myExistingProxy);

Next.js 12.2 to 15 uses middleware.ts, same wrapper:

// middleware.ts
import { withMentionFlow } from "@mentionflow/vercel";

export default withMentionFlow();

3. Set two env vars in Vercel → Project → Settings → Environment Variables (or your host's equivalent), then redeploy:

| Variable | Value | |---|---| | MENTIONFLOW_KEY | An API key from MentionFlow → Settings → API keys (mf_…) | | MENTIONFLOW_BRAND | Your brand id (MentionFlow → Agent analytics → connect panel) | | MENTIONFLOW_ENDPOINT | Self-hosted MentionFlow only: your ingest URL |

Both can also be passed in code: withMentionFlow(handler, { key, brand }).

Check that it works

Deploy, then pretend to be an AI crawler:

curl -A "GPTBot" -s -o /dev/null https://your-site.com/

Open MentionFlow → Agent analytics. The hit appears within about a minute ("Newest event on record" updates first). Nothing arriving? Check the deployment's function logs for a one-time [mentionflow] MENTIONFLOW_KEY / MENTIONFLOW_BRAND not set warning. It means the env vars didn't reach the deployment: set them for the right environment and redeploy.

Re-testing is safe. The server deduplicates repeated submissions.

What gets sent (and what doesn't)

• Only requests whose user-agent matches MentionFlow's AI-crawler registry are reported: one small POST per hit, sent after your response.
• The payload is timestamp, URL path, and user-agent string. No visitor traffic, no IPs, no headers, no query strings.
• HTTP status is not reported. The proxy runs before the route renders, so the status honestly isn't known yet. These events show a "—" status in MentionFlow (log-based ingestion paths do carry status).
• The package caps itself at 60 reports per minute per serverless instance (configurable via maxPerMinute), under MentionFlow's 120 req/min/key ingest limit. Beyond the cap, hits are dropped, never queued. This package must stay invisible to your site's performance.

Advanced

Hand-rolled proxy logic? Call the reporter yourself:

import { reportAiCrawler, AI_CRAWLER_UA } from "@mentionflow/vercel";

export default function proxy(request: Request, event: unknown) {
  reportAiCrawler(request, event); // fire-and-forget, never throws
  // ...your logic...
}

By default the proxy/middleware runs on every request, including _next/* assets. That mirrors what a CDN-level worker sees. If you scope your proxy with a matcher, crawler hits are only observed on matched routes. Keep the matcher broad if you want the full crawl picture.

Security notes

• Use a dedicated API key for this integration so you can revoke it independently (Settings → API keys).
• The key lives server-side in your deployment's env. Browsers never see it.