Quick start
- In the dashboard, create a key under Settings (Ayarlar) > API (MCP). Keys start with adv_ and are shown only once.
- Point your client at the address below with an Authorization: Bearer <key> header.
- 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/mcpAuthentication
Every request carries an Authorization: Bearer adv_… header. Keys are personal and bound to one workspace; a key works for as long as you are on the team.
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; the Owner and Admin roles can see and revoke the team's keys.
Every tool call is written to an audit log; entries are kept for 180 days.
Write tools re-read your role on every call: assigning categories and groups and adding competitors from a URL are open to Owner, Admin and Member; competitor class, adding social accounts and adding to the taxonomy to Owner and Admin. Viewers cannot write, and hidden workspaces accept no writes.
Client setup
Claude Code
One command in your terminal:
claude mcp add --transport http adversee https://adversee.com/api/mcp \
--header "Authorization: Bearer adv_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"Cursor
In ~/.cursor/mcp.json (or .cursor/mcp.json in your project):
{
"mcpServers": {
"adversee": {
"url": "https://adversee.com/api/mcp",
"headers": { "Authorization": "Bearer adv_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
}
}
}Claude Desktop
Claude Desktop's config file does not connect to remote servers directly; use the mcp-remote bridge (requires Node.js). Add this to claude_desktop_config.json and restart the app. Keeping the key in an environment variable avoids the Windows argument-spacing issue.
{
"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" }
}
}
}Plain HTTP
A JSON-RPC request for any MCP client or for testing:
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
Tools starting with adversee_set_, adversee_add_, adversee_update_ and adversee_close_, and adversee_undo_change, write; all others only read. Parameter names are shown exactly as the API expects them (they are Turkish). Most competitor filters accept a slug or a name; adversee_list_campaigns and adversee_get_banner_history accept a slug only. Slugs come from adversee_list_competitors.
adversee_list_competitors
Tracked competitors: name, slug, site, whether it is your own brand (kendiMarkamiz), active and archived campaign counts and tracking status (durum).
No parameters.
adversee_list_campaigns
Campaigns: title, link, status, the dates the site states, first and last seen (sonGorulme), removal detection (kaldirilmaTespiti), image address (gorselAdresi), category, group and how the category was set (kategoriElle: true manual, false model, null not interpreted yet). gorselAdresi points to the competitor's site; the image is not stored by us and cannot be fetched with adversee_get_image. Every item has rakipSlug; the list is wrapped with toplam, offset, kayit and devamiVar.
| Parameter | Type | Description |
|---|---|---|
rakip | slug | Competitor slug; names are not accepted. |
durum | aktif · yakinda · pasif · kaldirildi | Status: active, upcoming, inactive, removed. |
baslangic | ISO date-time with offset | Campaigns seen on the site after this moment. |
bitis | ISO date-time with offset | Campaigns first seen on the site before this moment. Together they select campaigns whose time on the site overlaps the range. |
limit | 1-100 (25) | Number of records. |
offset | ≥0 (0) | Pagination offset. |
adversee_get_campaign
One campaign: extracted fields (cap, wagering, rate), terms and all snapshots (newest first, each with kodSurumu).
| Parameter | Type | Description |
|---|---|---|
id | uuid | From adversee_list_campaigns. |
adversee_list_events
Events, newest first: campaign, banner, Meta, social post, outage and overtake events. Previous and new values of changed fields are in 'ayrinti'; for banner events ayrinti also carries the image's gorselId.
| Parameter | Type | Description |
|---|---|---|
rakip | string | Slug or name; use the slug for brands no longer tracked. |
tip | string | Comma-separated event types. Valid types: new_campaign, changed_campaign, changed_field, ended_campaign, reactivated_campaign, banner_eklendi, banner_kalkti, banner_guncellendi, meta_reklam_yeni, meta_reklam_bitti, meta_reklam_dondu, sosyal_paylasim_yeni, google_reklam_yeni, site_down, site_up, overtaken, regained, brand_ready. An unknown type returns an error. |
baslangic | ISO date-time with offset | From this moment (inclusive). |
bitis | ISO date-time with offset | Before this moment. |
cursor | string | sonrakiCursor from the previous response. |
limit | 1-100 (25) | Page size. |
adversee_get_digest
Daily (09:00) or weekly (Monday 09:00) digest: banner, Meta and social post counts per competitor. An unmeasured surface comes back as null, with its reason (olculmedi or eksik) given separately.
| Parameter | Type | Description |
|---|---|---|
donem | gun · hafta (gun) | Day or week. |
adet | 1-14 (1) | How many periods, newest first. At most 14 daily and 8 weekly periods are returned. |
adversee_list_homepage_banners
Homepage banners (desktop/mobile): stable id, position, target, first/last seen, removal time, previous version, last scan run per view and classification.
| Parameter | Type | Description |
|---|---|---|
rakip | string | Slug or name. |
durum | aktif · kalkan (aktif) | Live, or removed within the last 30 days. |
tur | teklif · icerik · marka_geneli | Type filter: offer, content, brand-level. With a filter, unclassified images are left out. |
kategori | string | Category key or name. |
grup | string | Game group key or name. |
oyun | string | Text contained in the game name on the image. |
adversee_get_banner_history
A competitor's banner order, scan run by scan run (one run every 2 hours). Runs are oldest first and paginated; the response has toplamTur, limit, offset, devamiVar and a kodSurumu on every run.
| Parameter | Type | Description |
|---|---|---|
rakip | slug | Required; names are not accepted. |
gorunum | masaustu · mobil | Required: desktop or mobile. |
baslangic | ISO date-time with offset | Defaults to 24 hours before the end. |
bitis | ISO date-time with offset | Defaults to now. Window is at most 366 days. |
limit | 1-500 (100) | Scan runs per page. |
offset | ≥0 (0) | Scan runs to skip. |
adversee_list_meta_ads
Meta (Facebook/Instagram) ads: library id and link, start date, first/last seen, end time, text, target, number of ads sharing the same creative (ayniGorselleReklam), video, text read from the image (gorseldenOkunan), gorselId, gorselLinki, classification and per-brand coverage. durum: biten returns the full history, paginated within the newest 2000 ended ads.
| Parameter | Type | Description |
|---|---|---|
rakip | string | Slug or name. |
durum | aktif · biten (aktif) | Active or ended ads. |
tur | teklif · icerik · marka_geneli | Type filter: offer, content, brand-level. With a filter, unclassified images are left out. |
kategori · grup · oyun | string | Same classification filters as the banner tool. |
limit | 1-100 (25) | Number of records. |
offset | ≥0 (0) | Pagination offset. |
adversee_get_image
A banner or ad image as an MCP image (png, jpeg, gif, webp; up to 3.7 MB). For video ads the image is the cover frame. Larger or other formats return a dashboard link.
| Parameter | Type | Description |
|---|---|---|
tur | banner · meta | Which surface the image comes from. |
gorselId | uuid | From the banner or Meta tool output. |
adversee_get_scan_status
Data freshness: for each competitor, the last scan run and last successful scan run for campaign scraping, banners (desktop/mobile) and every Meta page, the software version of the last run (sonTurKodSurumu) and the 7-day status breakdown; for campaign scraping, the number of campaigns found in the last successful run (sonBasariliTurdaBulunan). Each competitor's open health faults are in acikArizalar, and whether banner and Meta tracking is on is in yuzeyTakibi. Running scan runs are not counted; a partially read (kismi) Meta run does not count as successful. Times are ISO 8601 (UTC).
| Parameter | Type | Description |
|---|---|---|
rakip | string | Slug or name. |
adversee_list_competitor_notifications
Competitor push and SMS messages captured by the Notification Bridge: sender, text, first/last seen, how many times received and each receipt time on your own bridge (from October 6, 2026).
| Parameter | Type | Description |
|---|---|---|
rakip | string | Slug or name. |
baslangic | ISO date-time with offset | Seen at least once after this moment. |
bitis | ISO date-time with offset | First seen before this moment. |
limit | 1-100 (25) | Number of records. |
offset | ≥0 (0) | Pagination offset. |
adversee_get_overtakes
Where competitors beat you (e.g. cap, rate): open overtakes and recently closed ones.
No parameters.
adversee_list_taxonomy
The active taxonomy: campaign categories (key, name, description, aggressiveness) and game/product groups. The category and group tools accept these keys or names.
No parameters.
adversee_set_campaign_category
Writes. Sets or clears a campaign's category by hand; a manual category is kept in later AI interpretations. Owner, Admin, Member. Returns degisiklikId with the before and after state.
| Parameter | Type | Description |
|---|---|---|
kampanyaId | uuid | From adversee_list_campaigns. |
kategori | string | null | Category key or name; null clears it. |
adversee_set_campaign_group
Writes. Sets or clears a campaign's game/product group by hand. Owner, Admin, Member.
| Parameter | Type | Description |
|---|---|---|
kampanyaId | uuid | From adversee_list_campaigns. |
grup | string | null | Group key or name; null clears it. |
adversee_set_competitor_class
Writes. Sets a tracked brand's class to rakip (competitor) or bayi (reseller); your own brand cannot be changed. Owner, Admin.
| Parameter | Type | Description |
|---|---|---|
rakip | string | Slug or name. |
sinif | rakip | bayi | New class. |
adversee_add_social_account
Writes. Adds a YouTube, Instagram, TikTok or X account to a competitor; the account is verified on the platform, private or missing accounts are not added. Owner, Admin.
| Parameter | Type | Description |
|---|---|---|
rakip | string | Slug or name. |
platform | youtube | instagram | tiktok | x | Platform. |
hesap | string | URL or handle, e.g. @bilyoner. |
adversee_update_social_account
Writes. Replaces a competitor's followed social account with another: the old follow is closed and the new account is verified on the platform and added; if it cannot be verified the old follow stays open. If the new input resolves to the same account (only its name changed), the follow continues. Owner, Admin.
| Parameter | Type | Description |
|---|---|---|
rakip | string | Slug or name. |
platform | youtube | instagram | tiktok | x | Platform. |
eskiHesap | string | The account followed now. |
yeniHesap | string | The account to add instead, e.g. @bilyoner. |
adversee_add_meta_page
Writes. Adds a Facebook page to watch in the Meta Ad Library for a competitor; the page is added for this workspace only and read in the next Meta run. At most 5 extra pages per workspace. Owner, Admin.
| Parameter | Type | Description |
|---|---|---|
rakip | string | Slug or name. |
sayfa | string | Page id or Ad Library URL (view_all_page_id=…). |
adversee_close_meta_page
Writes. Stops following a Meta page this workspace added; ads already read are kept. Pages Adversee watches for everyone cannot be closed. Owner, Admin.
| Parameter | Type | Description |
|---|---|---|
rakip | string | Slug or name. |
sayfa | string | Page id or Ad Library URL. |
adversee_undo_change
Writes. Undoes a write made with the same key in the last 24 hours (except taxonomy additions), unless the record has changed since. Undoing a social account or Meta page addition closes the follow; the account is not deleted. Undoing an account change reopens the old follow; undoing a page close reopens the page.
| Parameter | Type | Description |
|---|---|---|
degisiklikId | uuid | The id from the write response. |
adversee_add_taxonomy_items
Writes, in two steps. Adds categories, game/product groups or extracted fields to the taxonomy; never deletes or renames. Called without onayKodu it changes nothing and returns the items to add, validation warnings and the impact (campaigns to reinterpret, images to reclassify, confirmation upper bound, estimated AI calls and tokens) with a confirmation code valid for 10 minutes. If the user approves, the same input with onayKodu applies it; campaigns and images are reprocessed in the background and it cannot be undone. Changes above the estimated call cap are refused; one per workspace per 24 hours; a new one waits until the previous reclassification finishes. Owner, Admin.
| Parameter | Type | Description |
|---|---|---|
kategoriler | list (≤10) | ad, optional key, aciklama, agresiflik (0-1). |
gruplar | list (≤10) | ad, optional key, aciklama. |
alanlar | list (≤10) | ad, tur, aciklama (≥20 characters), secenekler, birim, listedeGoster, izle, kiyas. Not filterable until measured. |
onayKodu | string | The code from the preview; only after the user approves. |
adversee_add_competitor
Writes, in two steps. Adds a new competitor from its site URL: starts tracking, derives the campaign list recipe with AI and runs the first scan (in the background). Called without onayKodu it changes nothing and returns the site, campaign path and plan quota with a confirmation code valid for 10 minutes. The competitor counts against the plan quota; its name is the site address. Public http(s) addresses only; IP and internal addresses are refused. Does nothing while adding competitors is turned off. 5 per hour per key, 20 per day per workspace. Cannot be undone. Owner, Admin, Member.
| Parameter | Type | Description |
|---|---|---|
url | string | Site or campaign page URL. |
onayKodu | string | The code from the preview; only after the user approves. |
adversee_seo_keywords
SEO / GEO / ASO (sold separately). Tracked search keywords: Google organic or app store search, group, monthly volume, last read day, our best rank, the best tracked competitor, 7-day rank change (positive = moved up), SERP features and AI Overview. hacim null = Google Ads gave no volume (not 0); bizimSira null with sonOkuma set = not in the first 'derinlik' results.
| Parameter | Type | Description |
|---|---|---|
kaynak | google · play · ios | Search source. |
grup | string | Keyword group (exact match). |
limit | 1-100 (25) | Number of records. |
offset | ≥0 (0) | Pagination. |
adversee_seo_sira_dagilimi
For each tracked domain or app, keywords on the latest read day split into rank buckets: 1-3, 4-10, 11-20, 21-50, 51-100, siralanmadi (not in the first K organic results of the read; K = kapsam, ~26-30 at depth 30, ~90-100 at depth 100; exact in every read). Beyond K nothing was measured, so the 21-50 / 51-100 buckets are null or kismi (a lower bound; olculenUst..olculenUstEnCok = the K range of the reads affecting the bucket). Change vs the previous day and 7 days ago counts only keywords read on both days, using the smaller K of the two reads per keyword (common coverage); buckets not fully measured under it have a null change.
| Parameter | Type | Description |
|---|---|---|
kaynak | google · play · ios | Search source (google). |
grup | text | Keyword group (exact match). |
adversee_seo_kelime_tablosu
Per keyword: our rank (sirada / disinda = not in the first N / okunmadi / tanimsiz = own domain not marked), bucket, URL, 1/7/30-day change (girdi/cikti/belirsiz when the number is null), every tracked competitor's rank, rakipOnde and SERP features. Filtering, sorting and paging run on the server.
| Parameter | Type | Description |
|---|---|---|
kaynak | google · play · ios | Search source (google). |
grup | text | Keyword group (exact match). |
kova | 1-3 · 4-10 · 11-20 · 21-50 · 51-100 · siralanmadi | Bucket of our rank. |
rakipOnde | true · false | Only keywords where a competitor is ahead. |
sirala | kelime · hacim · sira · g1 · g7 · g30 | Sort (sira). |
yon | artan · azalan | Direction; unknown values always last. |
limit | 1-100 (25) | Number of records. |
offset | ≥0 (0) | Paging. |
adversee_seo_youtube
Tracked YouTube keywords (Turkey, first 20 blocks, weekly by default): best video rank of your own and tracked competitor channels, change vs the previous read, channel visibility share (per read keyword, the 1/rank weight of the channel's videos ÷ the weight of all videos; keywords averaged equally) and, when a keyword is given, that read's videos (title, channel, views, published time, duration). Rank null with a read day = not in the first 'kapsam' videos; null values are not 0.
| Parameter | Type | Description |
|---|---|---|
kelime | uuid | Keyword whose videos to return (kelimeler[].id). |
adversee_seo_store_apps
Tracked Google Play and App Store apps: latest observation (installs are an exact number on Play only), rating, rating count, rank in the sports category (Play top 200, iOS top 100), version, 30-day category rank series and the two newest reviews.
| Parameter | Type | Description |
|---|---|---|
platform | play · ios | Store filter. |
adversee_seo_changes
Changes in tracked keywords, apps, domains and AI questions (newest first): changed field, previous and new value, importance and the AI commentary written for this workspace. Pagination: sonrakiOffset null means done.
| Parameter | Type | Description |
|---|---|---|
nesneTur | uygulama · kelime · alan · ai_soru · llm_marka | Object type. |
onem | yuksek · orta · dusuk | Importance filter. |
limit | 1-100 (25) | Number of records. |
offset | ≥0 (0) | Pagination. |
adversee_seo_backlinks
Without alan: summary of tracked domains with estimated organic traffic (etv) for the last 12 months, backlink summary and the number of new/lost backlinks seen in the stored list over 30 days. With alan: that domain's new or lost backlink list.
| Parameter | Type | Description |
|---|---|---|
alan | string | Tracked domain (e.g. bitalih.com). |
tur | yeni · kayip (yeni) | List type. |
limit | 1-100 (25) | Number of records. |
offset | ≥0 (0) | Pagination. |
adversee_seo_ai_visibility
Tracked questions × AI models (chatgpt, claude, gemini, perplexity): whether your own domain or brand was mentioned in the latest answer, which tracked domains were mentioned, sources and the start of the answer. yanit null = no answer for that model (not measured).
No parameters.
adversee_seo_ajan_hazirligi
Agent readiness (GEO): our own weekly crawl of tracked domains: robots.txt and Sitemap, each of 13 AI bots' permission (training, search and user-agent roles kept apart), Content-Signal, /llms.txt, Markdown content negotiation, text readable without JavaScript, JSON-LD types, MCP and A2A agent cards. Each check is var · yok · kismi · okunamadi with evidence and HTTP status; there is no total score. Effort-ordered recommendations for your own domains, with the competitors that already do it. okunamadi = the source could not be read (not 'missing').
No parameters.
adversee_seo_icerik_boslugu
Keywords where tracked competitors rank in Google's organic top 100 and your own domain does not; by volume (content suggestions). Group: your own keyword group or a rule-based guess (horse racing, sports, lottery). kesin false = our own list is truncated, so 'not ranking' could not be confirmed. One read per domain per month.
| Parameter | Type | Description |
|---|---|---|
kesin | true · false (false) | Confirmed gaps only. |
limit | 1-100 (25) | Number of records. |
offset | ≥0 (0) | Pagination. |
adversee_seo_ai_kaynaklari
Sites that AI answers cite as sources, by domain: in how many answers and questions, which models, and whether you and your competitors were mentioned in those answers. oneri true = not your own site and you were not mentioned in any answer citing it. No extra requests.
No parameters.
adversee_seo_llm_anilma
AI mentions (DataForSEO LLM Mentions), weekly: how often your brand and tracked competitors are mentioned in AI answers (database total, not a weekly increase), share among tracked brands and change against the previous week, cited domains, sample questions (every two weeks) and a 12 week series. In Turkey only Google AI Overview mentions; no ChatGPT data. Also returns the AI search volume of tracked Google keywords.
No parameters.
adversee_seo_kurulum_hizi
Daily install velocity of tracked Google Play apps: the change between two reads where the exact install count moved, divided by the time between them. An unchanged read means not updated, not zero installs. 7 and 28 day averages, share of new installs among tracked apps and a 28 day series. For the App Store only rating count growth is shown (not downloads). Velocity null = unknown.
No parameters.
adversee_seo_yorum_konulari
Topics in store reviews (rule-based Turkish dictionary, no AI): withdrawals, deposits, login/password, errors/crashes, odds/payouts, customer service, live streams, campaigns/bonuses. Brand × topic × week counts, sentiment from the rating, last 7 days against the previous 7 (rising for us, falling for competitors) and 7 days before and after a version change.
No parameters.
adversee_seo_icgoruler
marka_koruma: competitor ads and complaint sites in the top 3 on your brand keywords' SERP. cizelge: last 8 weeks, SEO moves per brand side by side with new banners, Meta ads and campaigns in the same week (not cause and effect). magaza_etki: category rank and install velocity 7 days before and after a store page change; insufficient data when there is too little.
| Parameter | Type | Description |
|---|---|---|
tur | marka_koruma · cizelge · magaza_etki | Insight type. |
adversee_seo_uygulama_kelimeleri
1-3 word candidate keywords from competitor apps' store title, subtitle and description: usage weight across competitors (title 3, subtitle 2, description 1), whether your own app uses it, whether it is tracked and, if so, the latest store rank. The demand score is a suggestion signal (0-100: the shortest prefix at which the keyword appears in App Store and Google Play search suggestions and its position there, plus Google volume when known), not search volume; null = not measured, kismi = a component is missing. Brand-name phrases are listed separately.
| Parameter | Type | Description |
|---|---|---|
marka | true · false | true: only candidates containing a brand name. |
limit | 1-100 | Maximum records (25). |
adversee_seo_inapp_eventler
In-app events shown on the tracked App Store apps' pages (read daily): name, description, start, end (empty when the page does not show it), first and last seen, the day it left the page, status. Last 120 days. Google Play events are out of scope.
| Parameter | Type | Description |
|---|---|---|
rakip | true · false | true: only competitors' events. |
adversee_seo_kelime_arastirmasi
Google keyword research run from the panel (Turkey, Turkish), from cache only: keyword, volume, CPC, competition, difficulty (0-100), search intent, whether it is tracked and which tracked domains rank for it (latest SERP or the monthly Labs list). The tool never runs a new research; new research is paid and runs from the panel.
| Parameter | Type | Description |
|---|---|---|
id | uuid | A research from the list. |
tohum | text | Latest research for this seed keyword. |
yontem | fikir · oneri · ilgili | Research method (fikir). |
limit | 1-100 (25) | Number of rows. |
offset | ≥0 (0) | Pagination. |
adversee_seo_teknik_sorunlar
Monthly full technical crawl of your own domain (DataForSEO On-Page; competitors are never fully crawled): latest crawl per domain, pages crawled, pages affected per issue type and a comparison with the previous crawl; affected pages in order of importance (broken internal links, 4xx/5xx, redirect chains, title and meta description, h1, noindex, canonical, slow and large pages). A page whose checks did not arrive is not counted as clean. New and fixed issues appear in the change log. Each domain carries its ownership verification status (approval, method: DNS TXT, meta tag, operator; last attempt and reason); the verification token is shown only in the panel.
| Parameter | Type | Description |
|---|---|---|
onem | yuksek · orta · dusuk | Importance filter. |
tur | kirik_link · kod_4xx · … · buyuk | Issue type. |
limit | 1-100 (50) | Number of records. |
offset | ≥0 (0) | Pagination. |
adversee_seo_arama_ilgisi
Weekly Google Trends curve for the last 12 months (Turkey) of the keywords selected for search interest. Each value is 1-100 relative to the keyword's OWN peak; keywords are not comparable to each other. New banners, Meta ads and campaigns in the same weeks are shown alongside (not cause and effect).
No parameters.
adversee_seo_lighthouse
Weekly mobile Lighthouse for each home page and the key URLs you pick (up to 20 on your own domain, 5 on a competitor): performance, accessibility, SEO and best practices scores, LCP, CLS and TBT; latest and previous run with a series, side by side with competitors. INP is not part of a lab run (null). A single run varies from run to run.
| Parameter | Type | Description |
|---|---|---|
gun | 30 · 90 · 180 (90) | Series window. |
Example questions
These questions can be answered with today's tools. Under each one is the tool the assistant uses and how.
- Which active banners have a confirmed campaign match? adversee_list_homepage_banners (durum: aktif). There is no confirmation filter; the assistant picks items where siniflama.onerilenKampanya.teyit.durum is teyitli.
- Which campaigns were removed in the last 30 days, and when? adversee_list_campaigns (baslangic: 30 days ago); items with kaldirilmaTespiti set have left the site, and the removal happened between sonGorulme and kaldirilmaTespiti. durum: kaldirildi only returns campaigns removed before their end date; those past it show as pasif.
- Which matches did our team reject? adversee_list_homepage_banners and adversee_list_meta_ads; the assistant picks items where teyit.durum is reddedildi and teyitEden is musteri.
- Show me the image of the banner added yesterday. adversee_list_events (tip: banner_eklendi, baslangic and bitis covering yesterday) gives ayrinti.gorselId; adversee_get_image (tur: banner) returns the image.
- Which banners were placed in position 1 over the last 3 months? adversee_get_banner_history (competitor slug, gorunum, baslangic: 3 months ago). While devamiVar is true, raise offset to get every scan run; the assistant picks items with sira 1.
- Which competitors are unreachable right now? adversee_get_scan_status; the acikArizalar list gives faults such as engelli and erisilemiyor.
- What have competitors posted on social media lately? adversee_list_events (tip: sosyal_paylasim_yeni). There is no separate social media tool; account data is not in MCP.
Example responses
Shortened; '…' marks omitted values. Field names are Turkish, as returned by the API; adversee_get_campaign is the exception and returns English keys.
adversee_get_banner_history
{
"marka": { "slug": "rakip-a", "ad": "Rakip A" },
"gorunum": "mobil",
"kayitBaslangici": "2026-10-06 11:50:16+00",
"toplamTur": 2, "limit": 100, "offset": 0, "devamiVar": false,
"turlar": [
{ "turId": "…", "zaman": "2026-10-07T10:00:12Z", "durum": "tamam", "kodSurumu": "…",
"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", "kodSurumu": "…",
"liste": null, "listeYokNedeni": "olculemedi" }
]
}adversee_list_events
{
"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", "slideId": "…", "gorselId": "…", "url": "https://…" } }
],
"sonrakiCursor": "b2xheTo…"
}Classification on banner and Meta items
"siniflama": {
"tur": "teklif",
"kategori": { "key": "hos_geldin", "ad": "Hoş Geldin" },
"grup": { "key": "spor_bonusu", "ad": "Spor Bonusu", "kaynak": "model" },
"oyun": "Rakip Slot",
"istemSurumu": 4,
"oyunTeyit": { "durum": "teyitli", "teyitEden": "ajan", "zaman": "…", "gerekce": "…" },
"onerilenKampanya": {
"id": "…", "baslik": "…", "guven": 85,
"teyit": { "durum": "aday", "teyitEden": null, "zaman": null, "gerekce": null }
},
"siniflandi": "2026-10-09T08:12:40.511Z"
}Limits
- Rate limit: 60 requests per minute per key; 429 when exceeded.
- Write limit: 10 writes per minute per key, 50 per hour per user and 100 per hour per workspace; the tool returns an error when exceeded. Undo is subject to the per-minute limit only.
- No batching: JSON-RPC batches are not supported; send one call per request.
- Body size: Request bodies up to 4 MiB.
- 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
| Status | Meaning |
|---|---|
401 | Missing, malformed or revoked key, or membership ended. |
429 | Per-minute request limit or invalid-key limit exceeded. |
400 | Body is not valid JSON, or a batch request was sent. |
413 | Body exceeds 4 MiB. |
406 | The Accept header does not include both application/json and text/event-stream. |
415 | The Content-Type header is not application/json. |
405 | The server is stateless; only POST is supported. |
isError | The tool ran but returned no result (e.g. 'Kayıt bulunamadı.', an invalid date or an unknown event type); the message explains why. |
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 scan run whose list is unknown has liste: null, and listeYokNedeni gives the reason: olculemedi (run failed), eksik (incomplete), kayit_hatasi (write error) or kayit_oncesi (before recording started).
- Banner order history is recorded from October 6, 2026; earlier successful scan runs return kayit_oncesi and failed ones olculemedi.
- 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. Each match is candidate (aday), confirmed (teyitli) or rejected (reddedildi); confirmation comes from a second AI check (ajan) or the workspace team (musteri), and the team's decision overrides the AI check. If the team confirmed a different campaign from the one the model suggested, guven is null. Do not use a rejected match as evidence.
- A Meta ad is marked ended only after it has been missing for at least 12 hours and at least 3 fully read scan runs.
- In Meta events, meta_reklam_yeni is an ad seen for the first time; an ad that had ended and reappears comes as a separate type (meta_reklam_dondu) and is not counted as new. The donen field in digests counts these.
- Competitor notifications keep each receipt time from October 6, 2026; older receipts only have first/last seen and a count (alimKaydiTam: false). alimlar contains only receipts from your own bridge (newest 20 per card, total in alimSayisi). The card itself is fed by the bridge of every workspace tracking the brand, and adet is the total across them. sonGorulme is the latest last-seen time among matching cards.
- The social media event sosyal_paylasim_yeni is a post published by a tracked account in the last 72 hours and seen for the first time. No event is written on an account's first read or after a read gap longer than 24 hours, so the sosyal field in digests counts only measured accounts and names the unmeasured ones in eksikKapsam.
- Before stating that something is absent or unchanged, check that surface's last successful scan run with adversee_get_scan_status.
What MCP cannot do
- Delete or change settings: dropping a competitor, closing a social follow without replacing it, closing a Meta page Adversee watches for everyone, deleting a category; adding competitors while that is turned off, deleting or renaming taxonomy items, notification preferences, team management, match confirmation.
- Start or refresh a scan; data is refreshed only by scheduled scan runs.
- Mark events as read.
- Access another workspace; a key is bound to one workspace.
- Read social account data; new posts only come through adversee_list_events as sosyal_paylasim_yeni.
- Backfill history: banner order history and per-receipt notification times start on October 6, 2026; campaign history starts when tracking began.
- Return dashboard screenshots, the full HTML of page snapshots or campaign images; banner and ad images are available through adversee_get_image.
- Batch requests; each tool call is its own request.