# SocialScout MCP server

Analyzed viral brand videos (5x+ breakouts with the brand behind each) and
1,600+ verified Flemish creators. Belgian/Flemish corpus, searchable in plain
language. This document is written for AI agents.

## Endpoint

    https://socialscout.be/api/mcp?key=YOUR_KEY

- Protocol: MCP, streamable HTTP (POST JSON-RPC). No SSE required.
- Auth: `?key=` query parameter, or `Authorization: Bearer <key>`.
- The SAME URL works without a key: only `create_account` and `corpus_stats`
  are available then. Every other tool answers with instructions.

## Getting a key (self-serve)

Call `create_account` with { email, name?, company?, access_code? }.
- With a valid access_code: response contains a working key immediately.
- Without: response contains a Stripe payment link (€110/month founding
  subscription); the key activates after payment.
- One account per email. Humans can also sign up at https://socialscout.be/account

## Tools

All tools return JSON as text content.

- create_account(email, name?, company?, access_code?) — see above.
- search_viral_videos(question, ads?, limit?) — semantic search over analyzed
  viral brand videos. question: plain-language description of the video or
  campaign. ads: "all" | "organic" | "ads". limit <= 30. Returns
  {video_id, brand, views, multiplier, is_ad, summary, link}[].
- search_creators(question, limit?) — plain-language casting brief over the
  creator corpus. limit <= 25. Returns {name, handle, followers, bio, link}[].
- top_breakouts(limit?, ads?, industry?, brand?) — the biggest brand
  breakouts (>=5x the account's normal). industry from list_sectors.
- creator_breakouts(limit?, ads?) — the biggest creator (person) breakouts.
- get_brand(handle) — one brand: stats, top breakouts, creators seen with.
- get_creator(handle) — one creator: stats, best videos, brands on screen.
- get_video(video_id) — full analysis: summary, format, topics, numbers,
  creator, brands, link.
- list_sectors() — sectors with breakout counts, for the industry filter.
- corpus_stats() — corpus totals. Available without a key.

## Prompts

- plan_campaign(sector) — grounded campaign-planning workflow: fetch
  breakouts, derive proven formats, cast a shortlist, cite every claim.
- creator_shortlist(brief) — grounded casting workflow.

## Grounding rules

Claims about videos, creators or brands must come from tool results. The
corpus is Belgian/Flemish; multipliers mean "x times the account's median".
Every result carries a link to the human-readable page on socialscout.be.

## Example (JSON-RPC over HTTP)

    POST https://socialscout.be/api/mcp?key=YOUR_KEY
    Content-Type: application/json
    Accept: application/json, text/event-stream

    {"jsonrpc":"2.0","id":1,"method":"tools/call",
     "params":{"name":"top_breakouts","arguments":{"limit":5,"industry":"food"}}}

## Metering & plans

Every tool call is metered per key. Plans: subscription (unlimited fair use)
or enterprise per-interaction (mail hendrik@vibelab.be). Human documentation:
https://socialscout.be/agents