Add KOLens as a Custom Connector in Claude (MCP + OAuth 2.1)

Why MCP changes the integration story

Until now, "use KOLens from an AI" meant one of two things: either install a stdio MCP plugin in Claude Desktop (works, but single-machine and single-user) or paste an API key into your Continue config and hope Continue doesn't leak it (works, but every prompt has to remember which API to call).

Custom Connectors collapse both into a network protocol. KOLens publishes its tool surface at one URL; Claude.ai (or any MCP client) discovers it; users authenticate once via OAuth and the connection persists. From the user's side it's "I added a thing to Claude" — same affordance as adding a Slack integration.

Setup in 60 seconds

1. 1

   In Claude.ai → Settings → Connectors → Add custom connector.

   (The exact path may vary slightly across Claude clients; look for "Custom connector" in any Connectors / MCP settings panel.)
2. 2

   Paste https://kolens.ai/mcp and hit Connect.

   Claude fetches our discovery docs at /.well-known/oauth-authorization-server + /.well-known/oauth-protected-resource, sees that we speak OAuth 2.1, and self-registers via POST /oauth/register (RFC 7591 dynamic client registration).
3. 3

   You're bounced to a KOLens consent page.

   The page shows which scopes Claude is asking for — read:kols + write:lists in the default request — and lists the tools each scope unlocks. Click Approve.
4. 4

   Claude gets a 1-hour access token + a refreshable refresh token.

   You're returned to Claude with the connection live. The access token expires every hour; Claude rotates it automatically using the refresh token without bothering you.

What Claude can do once connected

15 tools across 3 scopes:

read:kols — research

• list_kols — query the accumulated KOL database (filter by keyword, role, follower count, etc.)
• get_kol_profile — full KOLens profile for one TikTok handle
• list_recent_jobs + get_job_status — your recent scrape runs
• list_advertisers + get_advertiser_ads — Facebook Ad Spy data
• list_discovery_plans — your scheduled keyword scrapes
• list_alerts — recent growth alerts (rising_kol, trending_video, audience_drift)
• get_audience_snapshot — latest sampled-follower snapshot
• list_kol_lists + get_list_members — your curated lead lists
• list_watchlist — your tracked KOLs

write:lists — small mutations

• add_to_watchlist / remove_from_watchlist — manage tracking
• mark_alert_read — clear notifications

run:scrape — paid actions (not requested by default)

Reserved for tools that charge credits (kicking off a fresh keyword scrape, running a handle lookup, generating a new audience snapshot). Claude doesn't ask for this scope in the default consent request — you'd have to explicitly grant it on a future re-auth — so a careless prompt can't accidentally spend $20 of credits.

Security model

• PKCE required — public clients can't skip the verifier exchange. code_challenge_method=S256 only; the plain fallback that RFC 7636 permits is disallowed.
• Opaque tokens, not JWT — cheaper to revoke (single column flip) and doesn't leak claims to anyone snooping the wire. The kolens_at_… prefix makes them scannable in logs without decoding.
• Hashed at rest — only SHA-256 hashes hit the DB. A leak of the database alone can't be replayed against the API.
• Single-use auth codes — replay sets a used_at marker and the code becomes inert.
• Per-user revocation — Disconnect from /account/connections bulk-revokes every live token for that (user, client) pair. Cascades from refresh → paired access tokens so it feels atomic.

Useful prompts

• "Find me 5 phonecase TikTok creators with email + at least 50K followers" → Claude calls list_kols with the right filters.
• "Star CompetitorX on my Ad Spy watchlist" → resolves the page name to an advertiser_id then calls a future watch tool (read-only today; write tool coming with the next MCP-3 expansion).
• "What's the audience country mix for @minicaseco?" → get_audience_snapshot returns the latest snapshot or { snapshot: null } if none exists yet, prompting Claude to suggest you run one.
• "Mark the rising_kol alerts about @uglycaseguy as read" → list + filter + bulk mark_alert_read.

What's next

Streaming responses for long-running tools, Supabase-cookie-based consent (so the consent page doesn't ask for an API key), per-tool budget caps, refresh-token rotation. None block usage today; the connector works end-to-end.