Asonix MCP

MCP tools

The Asonix MCP server at https://api.asonix.io/mcp gives your agent these 33 tools. You do not call them yourself: ask in plain words, and your agent picks the tools it needs. This page lists what each tool does and the inputs it takes.

Set up the MCP server

get_ai_visibility_overview

Read-only

AI Visibility Overview

Read a tracked app's stored AI recommendation benchmark: coverage, mention/recommendation/App Store citation rates, weekly history and topic/prompt summaries with run IDs. Not ASO visibility. No collection or model calls. Defaults to four weeks; no benchmark returns NOT_STARTED. Use list_apps to resolve the app and storefront.

appStoreIdstringRequired1–128 characters
countrystringOptionalExact storefront, e.g. us. Defaults to us; use the tracked app's home country
platformstringOptionalOne of: ios, ipad, mac
weeksintegerOptional1–12. Default: 4

get_ai_visibility_reasons

Read-only

AI Recommendation Reasons

Read cached recommendation themes, exact answer quotes and description passage matches. Includes analysis status, timestamps and its own evidence denominator (which can differ from the overview). No generation or refresh. Full descriptions stay in get_app_overview; this returns matched passages and description metadata. Use theme and evidenceLimit to drill into supporting quotes.

appStoreIdstringRequired1–128 characters
countrystringOptionalExact storefront, e.g. us. Defaults to us; use the tracked app's home country
platformstringOptionalOne of: ios, ipad, mac
themestringOptional1–200 characters
evidenceLimitintegerOptional1–10. Default: 3

get_ai_visibility_evidence

Read-only

AI Visibility Evidence

Read a saved AI Visibility answer by runId, or recent answers for one promptId (exactly one required). Defaults to one run; use nextBefore for older prompt runs. Citations, resolved mentions and classification coverage are included. includeTrace adds captured searches; their sources belong to a search call, not an individual query. No external requests or collection.

Give exactly one of: runId, promptId.

appStoreIdstringRequired1–128 characters
countrystringOptionalExact storefront, e.g. us. Defaults to us; use the tracked app's home country
platformstringOptionalOne of: ios, ipad, mac
runIdstringOptional1–128 characters
promptIdstringOptional1–128 characters
beforestringOptionalExclusive scheduledFor cursor from nextBefore; only with promptId. Format: date-time
limitintegerOptional1–5. Default: 1
includeTracebooleanOptionalDefault: false

add_app

Makes changes

Add App

Add an App Store app to the current Asonix workspace by App Store ID or app name/search query.

appStoreIdstringOptional
countrystringOptional
namestringOptional
platformstringOptionalOne of: ios, ipad, mac
qstringOptional

create_unreleased_app

Makes changes

Create Unreleased App

Create a private unreleased app idea in the current Asonix workspace. Use this when the user's app is not on the App Store yet; then add researched keywords with add_keywords.

countrystringOptional
namestringOptional
platformstringOptionalOne of: ios, ipad, mac

search_apps

Read-only

Search Apps

Find App Store apps by name or developer, to get an app's appStoreId; use it before add_app when the user gives an app name. Returns at most 12 apps, in Apple's name-search order, which is not the keyword ranking: for who ranks for a keyword, use get_keyword_top_apps. Screenshot URLs only with includeScreenshots.

countrystringOptional
includeScreenshotsbooleanOptionalInclude each app's screenshot URLs. Omitted by default: they were two thirds of an answer
limitintegerOptional1–12
platformstringOptionalOne of: ios, ipad, mac
qstringRequired

add_keywords

Makes changes

Add Keywords

Add one or more tracked keywords to an app in the current Asonix workspace and queue ranking refresh so popularity, difficulty, opportunity, and rank evidence can be collected. For agent-researched candidates, call evaluate_keywords first and add app-relevant primary or secondary terms.

appStoreIdstringRequired
countrystringOptional
keywordsarray of stringRequiredAt least 1 item
platformstringOptionalOne of: ios, ipad, mac

star_keyword

Makes changes

Star Keyword

Star/favorite a keyword research keyword in the current workspace by keywordId or term.

countrystringOptional
keywordIdstringOptional
termstringOptional

unstar_keyword

Makes changes

Unstar Keyword

Remove a keyword research keyword from the current workspace favorites by keywordId or term.

countrystringOptional
keywordIdstringOptional
termstringOptional

list_apps

Read-only

List Apps

List apps tracked in the current Asonix workspace: names, App Store IDs, platforms, tracked storefronts, ratings and tracked-keyword counts. Pages with limit (default 20, max 100) and offset; q filters by name, developer, genre or ID. For one app's details use get_app_overview; for its keywords, list_tracked_keywords.

limitintegerOptional1–100
offsetintegerOptionalAt least 0
platformstringOptionalOne of: ios, ipad, mac
qstringOptional

list_tracked_keywords

Read-only

Tracked Keywords

One tracked app's tracked keywords with rank, popularity, difficulty, relevance and an ad summary, in one storefront or all. Use it for "how are my keywords doing". For the app's listing or ratings, or an untracked app, use get_app_overview. Paged: limit (default 30, max 100) and offset. relatedTools gives the next page, refresh_app_rankings when ranks are over 18 hours old, and the overview.

appStoreIdstringRequired
countrystringOptional
limitintegerOptional1–100
offsetintegerOptionalAt least 0
platformstringOptionalOne of: ios, ipad, mac

get_app_meta_ads

Read-only

App Meta Ads

An App Store app's Meta ads (Facebook, Instagram, Messenger, Audience Network) from Asonix's monthly Ad Library crawl, worldwide, for any app: active ads with text, call to action, start date, platforms and an Ad Library link, and past ads with their dates. status not_found is not proof it never ran Meta ads: the crawl covers the App Store ads it found.

appStoreIdstringRequired

refresh_app_rankings

Makes changes

Refresh App Rankings

Queue a ranking refresh for one tracked app's keywords not checked in the last 18 hours, and return at once with jobIds. Omit country for every tracked storefront; one refreshed recently is listed in coolingDown. A refresh can take 10 minutes or more, so do not wait in a loop: tell the user ranks are updating, then call get_ranking_refresh_status after pollAfterSeconds, or read list_tracked_keywords later.

appStoreIdstringRequired
countrystringOptional
platformstringOptionalOne of: ios, ipad, mac

get_ranking_refresh_status

Read-only

Ranking Refresh Status

Report progress of a ranking refresh started by refresh_app_rankings, or of the rankingRefreshJob id returned by add_keywords: keywords done, failed, and remaining per storefront. Poll no more often than pollAfterSeconds. When finished is true, read the full updated ranks with list_tracked_keywords.

jobIdsarray of stringRequired1–20 items

get_workspace_keyword_opportunities

Read-only

Workspace Keyword Opportunities

Return top scored keyword opportunities across all tracked apps in the current Asonix workspace, including shipped and unreleased apps, all countries, and rank/popularity/difficulty/opportunity evidence. Use this for requests like analyzing all apps or finding the top 100 opportunities without reading a local database. Each opportunity has checkedAt; call refresh_app_rankings for an app whose ranks are old.

countrystringOptional
limitintegerOptional1–200
platformstringOptionalOne of: ios, ipad, mac

check_tracked_keywords

Read-only

Check Tracked Keywords

Check candidate keyword terms against one tracked app's existing tracked keywords without dumping the full keyword table. iOS keyword rows include cached topAdvertisers; pending observations queue in the background. Use this before calling a candidate a missing gap, before add_keywords, and instead of inspecting local database code.

appStoreIdstringRequired
countrystringOptional
keywordsarray of stringRequiredAt least 1 item
platformstringOptionalOne of: ios, ipad, mac

get_app_overview

Read-only

App Overview

An app's overview in one storefront, for any App Store app. storeListing is the storefront's listing and rating. Lists are counts: include adds the full description, countryRatings, listingCountries or keywordSuggestions. tracked says whether the workspace tracks it; its keywords: list_tracked_keywords. runsAppleSearchAds: yes if a sampled search ad showed the app in any country Asonix samples (7 days); unknown is not proof it does not advertise.

appStoreIdstringRequired
countrystringOptional
includearray of stringOptionalFull lists to add: description, countryRatings, listingCountries, keywordSuggestions. Each item: One of: description, countryRatings, listingCountries, keywordSuggestions
platformstringOptionalOne of: ios, ipad, mac

get_app_visibility_history

Read-only

App Visibility History

Return tracked ASO visibility score history for an app, useful for momentum and trend analysis.

appStoreIdstringRequired
daysintegerOptional2–30
platformstringOptionalOne of: ios, ipad, mac

get_app_rank_history

Read-only

App Rank History

Return rank, popularity, or difficulty history for one tracked app keyword in a storefront.

appStoreIdstringRequired
countrystringOptional
keywordstringRequired
metricstringOptionalOne of: rank, popularity, difficulty
platformstringOptionalOne of: ios, ipad, mac

get_app_rating_history

Read-only

App Rating History

Return stored public rating history for any App Store app, tracked or not, with deltas: the history the Inspect dialog shows. Asonix records rating history only while some workspace tracks the app, so an app no workspace has tracked has none; for current ratings of any app, use get_app_overview. Omit country or pass "all" to return every observed storefront plus the all-countries aggregate; pass a country code to return only that storefront.

appStoreIdstringRequired
countrystringOptionalOptional App Store country to return. Omit it or pass "all" to return every stored country and the all-countries aggregate
platformstringOptionalOne of: ios, ipad, mac

get_app_charts

Read-only

App Top Charts

Where any App Store app placed in Apple's iPhone top charts (free, paid, grossing; overall and by category) per storefront: best rank, days on chart, latest position. days: 7, 30 (default), 90 or 365. includeDailyCells adds a cell per chart per day: a number is the best position, -N absent from the top N, e empty chart, x not captured, u not collected yet, p pending; 90 and 365 days cover one storefront. iPad and Mac apps: iphone_only.

appStoreIdstringRequiredmatches ^[1-9][0-9]{0,18}$
countrystringOptional
daysintegerOptionalOne of: 7, 30, 90, 365
includeDailyCellsbooleanOptional
platformstringOptionalOne of: ios, ipad, mac

get_keyword_suggestions_for_app

Makes changes

App Keyword Suggestions

Refresh and return Asonix keyword suggestions for one tracked app and storefront. Includes suggestionRelevance rows and inline metadata-plan relevanceScore/relevanceStatus; missing scores queue in the background.

appStoreIdstringRequired
countrystringOptional
platformstringOptionalOne of: ios, ipad, mac

research_app_keywords

Makes changes

Research App Keywords

Start keyword research for a tracked app in one call: Asonix suggestions, known public rankings and market keyword opportunities, each with the app's relevance. It can refresh the suggestion list, which spends the app's daily budget. Seed searches are checked privately unless storePublicly is true. Pending ad observations and relevance scores fill in on a later call. Classify candidates with evaluate_keywords before recommending or adding them.

appStoreIdstringRequired
countrystringOptional
excludeBrandsbooleanOptional
competitorLimitintegerOptional1–10
includeCompetitorsbooleanOptional
limitintegerOptional1–25
platformstringOptionalOne of: ios, ipad, mac
qstringOptional
refreshSuggestionsbooleanOptional
seedstringOptional
sortstringOptionalOne of: revenue, downloads, opportunity, popularity, difficulty
storePubliclybooleanOptional

extract_competitor_keywords

Makes changes

Competitor Keywords

Extract keyword opportunities from competitor public rankings and compare them against the tracked app. Includes relevanceScore/relevanceStatus for the target app, not the competitors; missing scores queue in the background. Provide competitorAppStoreIds, or provide a seed keyword to discover competitors from a private live SERP unless storePublicly is true. Rank and classify candidates with evaluate_keywords before recommending or adding them.

appStoreIdstringRequired
competitorAppStoreIdsarray of stringOptional
competitorIdsarray of stringOptional
competitorLimitintegerOptional1–10
competitorsarray of stringOptional
countrystringOptional
keywordstringOptional
limitintegerOptional1–25
platformstringOptionalOne of: ios, ipad, mac
qstringOptional
seedstringOptional
storePubliclybooleanOptional

get_localization_opportunities

Makes changes

Localization Opportunities

Build and return localization and translated market keyword opportunity requests for one tracked app.

appStoreIdstringRequired
platformstringOptionalOne of: ios, ipad, mac

get_public_app_rankings

Read-only

Public App Rankings

Return known public App Store keyword rankings where an app appears in collected SERPs.

appStoreIdstringRequired
countrystringOptional
limitintegerOptional1–20
offsetintegerOptionalAt least 0
platformstringOptionalOne of: ios, ipad, mac

search_keywords

Read-only

Search Keywords

Search Asonix keyword research summaries by query, market, platform, scores, and market estimates. iOS keyword rows include cached topAdvertisers; pending observations queue in the background, so retry this tool later.

countrystringOptional
excludeBrandsbooleanOptional
limitintegerOptional1–100
maxDifficultyintegerOptional0–100
maxDownloadsintegerOptionalAt least 0
maxKeywordLengthintegerOptionalAt least 1
maxOpportunityintegerOptional0–100
maxPopularityintegerOptional0–100
maxRevenueintegerOptionalAt least 0
minDifficultyintegerOptional0–100
minDownloadsintegerOptionalAt least 0
minOpportunityintegerOptional0–100
minPopularityintegerOptional0–100
minRevenueintegerOptionalAt least 0
pageintegerOptionalAt least 1
platformstringOptionalOne of: ios, ipad, mac
qstringOptional
sortstringOptionalOne of: revenue, downloads, opportunity, popularity, difficulty
starredbooleanOptional

get_keyword_relevance

Read-only

Keyword Relevance

App-specific relevance (0–100) of up to 100 keywords for a tracked app, from the same scorer as the UI. Returns at once with ready, pending, failed or unavailable for each keyword. Pending is not zero: call again after 3 seconds or more, backing off. retry=true retries failed work after its cooldown. Adds nothing to tracking or public research. country defaults to us and platform to ios.

appStoreIdstringRequiredAt least 1 character
countrystringOptional
platformstringOptionalOne of: ios, ipad, mac
keywordsarray of stringRequired1–100 items. Each item: 1–200 characters, not blank
retrybooleanOptional

evaluate_keywords

Makes changes

Evaluate Keywords

Rank and classify candidate keywords by Asonix popularity, difficulty and opportunity. Use it before recommending keywords or calling add_keywords. Known keywords reuse stored scores; up to 20 new ones per call are scored privately, without adding them to public research. Pass popularityScore and difficultyScore to judge your own values. appStoreId adds app relevance; pending is not zero (get_keyword_relevance).

appStoreIdstringOptionalOptional tracked target app for inline relevance scores. At least 1 character
countrystringOptional
excludeBrandsbooleanOptional
keywordsarray of string or objectRequired1–50 items. Object fields: difficultyScore (0–100), keyword, opportunityScore (0–100), popularityScore (0–100), term
maxDifficultyintegerOptional0–100
minOpportunityintegerOptional0–100
minPopularityintegerOptional0–100
platformstringOptionalOne of: ios, ipad, mac

get_keyword_top_apps

Read-only

Keyword Top Apps

Who ranks for a keyword in one storefront; appStoreId gives that app's rank. Uses results Asonix checked in the last 18 hours, else a private live check; saves nothing. Adds stored scores when Asonix has them; to score a new keyword, use evaluate_keywords. To find an app by name, use search_apps. runsAppleSearchAds: yes if a sampled search ad showed the app in any country Asonix samples (7 days); unknown is not proof it does not advertise.

appStoreIdstringOptionalAn app to find in the results: targetApp gives its rank, also beyond limit
countrystringOptional
includeScreenshotsbooleanOptionalInclude screenshot URLs for the first 10 apps
keywordstringOptionalThe keyword text. Give this or keywordId
keywordIdstringOptionalAn Asonix keyword ID, from search_keywords for example
limitintegerOptional1–100
platformstringOptionalOne of: ios, ipad, mac

get_keyword_top_advertisers

Read-only

Keyword Top Advertisers

Apps seen in native App Store search ads for one iPhone keyword in one Apple Ads country: the last 7 days' check coverage, last seen, and 30 days of history. Cached only, no live Apple request; pending collection fills in on a later call. Absence does not prove an app stopped bidding or was outbid. Needs country and exactly one of keywordId or term.

countrystringRequiredOne of 91 values: ae, al, am, ar, at, …
keywordIdstringOptional1–100 characters
termstringOptional1–200 characters
platformstringOptionalOne of: ios

get_app_search_ads_keywords

Read-only

App Paid Keywords

Keywords where an iPhone app's App Store search ads were seen in the last 30 days, in all countries or one. Asonix checks each keyword about once a day, so a missing keyword may still be bid on. observedSharePercent7d is the share of the last 7 days' checks that showed the ad, not impression share. organicRank is null when the app is not in the latest results. status unavailable means ad data is off, not no ads.

appStoreIdstringRequiredmatches ^[0-9]{1,20}$
countrystringOptionalOne of 91 values: ae, al, am, ar, at, …

get_keyword_history

Read-only

Keyword History

Return keyword popularity or difficulty history for an Asonix keyword, with cached topAdvertisers for eligible iOS keywords. Pending advertiser observations are queued; retry later.

countrystringOptional
keywordIdstringRequired
metricstringOptionalOne of: popularity, difficulty
platformstringOptionalOne of: ios, ipad, mac
Back to Asonix