Adversee MCP server

Quick start

1. In the dashboard, create a key under Settings (Ayarlar) > API (MCP). Keys start with adv_ and are shown only once.
2. Point your client at the address below with an Authorization: Bearer <key> header.
3. If your client lists the tools, you are connected. For a first try, ask the assistant for your competitor list.

Server URL

https://adversee.com/api/mcp

Authentication

Every request carries an Authorization: Bearer adv_… header. Keys are personal and bound to one workspace; the assistant sees that workspace with your role.

Each request re-checks that the key is not revoked, your account is active and you are still on the team. Users removed and re-invited must create a new key.

Each user can hold at most 10 active keys per workspace. Keys are revoked from the dashboard.

Client setup

claude mcp add --transport http adversee https://adversee.com/api/mcp \
  --header "Authorization: Bearer adv_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

{
  "mcpServers": {
    "adversee": {
      "url": "https://adversee.com/api/mcp",
      "headers": { "Authorization": "Bearer adv_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
    }
  }
}

{
  "mcpServers": {
    "adversee": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://adversee.com/api/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${ADVERSEE_AUTH}"
      ],
      "env": { "ADVERSEE_AUTH": "Bearer adv_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
    }
  }
}

curl -s https://adversee.com/api/mcp \
  -H "Authorization: Bearer adv_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"adversee_list_competitors","arguments":{}}}'

Tools

All tools are read-only. Parameter names are shown exactly as the API expects them (they are Turkish). Competitor filters accept a slug or a name; slugs come from adversee_list_competitors.

Example responses

Shortened; '…' marks omitted values. Field names are Turkish, as returned by the API.

{
  "marka": { "slug": "rakip-a", "ad": "Rakip A" },
  "gorunum": "mobil",
  "kayitBaslangici": "2026-10-06 11:50:16+00",
  "turlar": [
    { "turId": "…", "zaman": "2026-10-07T10:00:12Z", "durum": "tamam",
      "liste": [
        { "sira": 1, "slideId": "…", "gorselId": "…", "hedef": "https://…", "gorselLinki": "https://adversee.com/app/panel-api/vitrin/gorsel/…" },
        { "sira": 2, "slideId": "…", "gorselId": "…", "hedef": null, "gorselLinki": "…" }
      ] },
    { "turId": "…", "zaman": "2026-10-07T12:00:09Z", "durum": "engel",
      "liste": null, "listeYokNedeni": "olculemedi" }
  ]
}

{
  "hareketler": [
    { "id": "…", "tip": "banner_eklendi", "baslik": "…", "rakip": "Rakip A",
      "rakipSlug": "rakip-a", "seviye": "hamle", "zaman": "2026-10-07T10:00:12.318Z",
      "kampanyaId": null, "ayrinti": { "gorunum": "mobil", "url": "https://…" } }
  ],
  "sonrakiCursor": "b2xheTo…"
}

"siniflama": {
  "tur": "teklif",
  "kategori": { "key": "ek_kazanc", "ad": "Ek Kazanç" },
  "grup": { "key": "bas_kazan", "ad": "Bas Kazan" },
  "oyun": "Efsane Mücevher Avcısı",
  "istemSurumu": 2,
  "onerilenKampanya": { "id": "…", "baslik": "…", "guven": 85 }
}

Limits

• Rate limit: 60 requests per minute per key; 429 when exceeded.
• No batching: JSON-RPC batches are not supported; send one call per request.
• Body size: Request bodies up to 4 MB.
• Image size: Images up to 3.7 MB are returned as images; larger ones return a dashboard link.
• Invalid keys: More than 20 invalid-key attempts per minute from one address get 429; valid keys are not affected.
• Freshness: Banners are checked every 2 hours, Meta every 6 hours; polling more often brings nothing new.

Error codes

Reading the data correctly

• null means 'unknown', not 'none'. Values that could not be measured are never reported as 0.
• In banner order history a failed tour has liste: null, and listeYokNedeni gives the reason: olculemedi (not measured), eksik (incomplete), kayit_hatasi (write error) or kayit_oncesi (before recording started).
• Banner order history is recorded from 6 October 2026; earlier tours return kayit_oncesi.
• When polling events, set baslangic to 15 minutes before your last pull and de-duplicate by id; rows written at the same moment can appear a few seconds late.
• Date parameters need a time zone (e.g. 2026-10-07T00:00:00Z or +03:00).
• Meta shows logged-out visitors only the first page of large pages, and some pages not at all. The 'kapsam' field states this per brand; counts are distinct ad creatives.
• Image classification is an AI estimate: uncertain fields stay null, the game name is given only if it is written on the image, and campaign matches are confidence-scored suggestions, not hard links.
• A Meta ad is marked ended only after it has been missing for at least 12 hours and at least 3 fully read tours.