How access works
Every tool runs as you and only sees the websites in your own workspaces. Two kinds of token decide what a tool can do:- A read-only token can call every tool that reads data. That is all but the five write tools.
- A read & write token additionally allows the write tools
create-prompt,update-prompt,create-competitor,update-competitor, andremove-competitor, which add or edit your tracked prompts and competitors.
Set up the server and tokens
How to connect a client and create read-only or read & write tokens.
Parameters most tools share
A few parameters and response fields repeat across the read tools, so they are described once here rather than in every table.| Parameter | What it does |
|---|---|
website_id | The website to scope to. Optional on almost every tool: when omitted it falls back to your currently selected website, or your only website. Call list-websites first to get valid IDs. |
range_days | A look-back window of 7, 30, or 90 days. On the overview, analytics, and gap tools it defaults to 30. On the other list tools it is optional, and omitting it returns all time. |
since | An ISO 8601 timestamp. Returns only rows created at or after that moment, and overrides range_days when both are passed. Use it for “everything since my last check”. |
limit | Caps how many rows come back. For most list tools the default is 50 and the maximum is 250. |
List tools return a
returned, total, and truncated field alongside the rows, so you can tell when results were capped by limit and need a tighter filter.Overview and digest
High-level health and a one-call daily bundle.| Tool | What it returns | Key parameters | Access |
|---|---|---|---|
get-visibility-overview | Headline metrics for a website: visibility score, run counts, share of voice versus competitors, top cited domains, answer-gap count, and community source coverage. Includes previous and delta blocks comparing the window against the one before it. | website_id, range_days | Read |
get-daily-digest | A single monitoring bundle: brand and competitor mentions, new social mentions, the overview with period-over-period deltas, and answer gaps that newly opened, all since a timestamp. | website_id, since, range_days, limit | Read |
get-brand-profile | The brand context MentionScout tracks: brand terms, descriptions, industry, competitors, and audience personas. Useful for grounding suggestions. | website_id | Read |
Prompts
Read and manage the tracked prompts MentionScout runs against the answer engines.| Tool | What it does | Key parameters | Access |
|---|---|---|---|
list-prompts | Lists tracked prompts with their providers, intent, type, frequency, enabled state, and last run time. | website_id, enabled, limit | Read |
create-prompt | Creates a new tracked prompt. | text (required), providers (required), intent, prompt_type, frequency, country, language, enabled, tags, website_id | Read & write |
update-prompt | Edits an existing prompt. Only the fields you pass change; passing an empty providers array removes all providers. | prompt_id (required), text, providers, intent, prompt_type, frequency, country, language, enabled | Read & write |
providers field takes provider slugs, for example openai (ChatGPT), anthropic (Claude), gemini (Gemini), or perplexity (Perplexity). create-prompt respects your plan’s prompt limit and returns an error if you are already at the cap.
“Tracked prompts” here are the questions MentionScout runs on a schedule, managed on the Prompts page. They are different from the MCP prompts described lower on this page.
Competitors
Read and manage the competitors in a website’s brand profile. To edit or remove one you need its ID, whichget-brand-profile returns.
| Tool | What it does | Key parameters | Access |
|---|---|---|---|
create-competitor | Adds a competitor to a website’s brand profile. | name (required), domain, aliases, description, website_id | Read & write |
update-competitor | Edits an existing competitor. Only the fields you pass change; an empty aliases array clears all aliases. | competitor_id (required), name, domain, aliases, description | Read & write |
remove-competitor | Removes a competitor from the brand profile. | competitor_id (required) | Read & write |
Competitors are part of the brand profile you set up on the Competitors page. Read the current list with
get-brand-profile, which returns each competitor’s ID.Runs
A run is one prompt sent to one engine. These tools read the run log.| Tool | What it returns | Key parameters | Access |
|---|---|---|---|
list-runs | Prompt runs for a website, newest first. Includes both seed runs and fan-out sub-query runs. | website_id, prompt_id, provider, range_days, since, limit, seed_only | Read |
get-run | One run in full: the raw AI answer text, the sources it cited, and the brand and competitor mentions detected in it. | run_id (required) | Read |
seed_only as true to list-runs to exclude fan-out sub-query runs and see only the original prompt text. See Query fan-out for how those sub-queries are generated.
Mentions and citations
The parsed output of every run, rolled up across the website.| Tool | What it returns | Key parameters | Access |
|---|---|---|---|
list-mentions | Brand and competitor mentions found in AI answers, newest first. | website_id, subject (own or competitor), provider, range_days, since, limit | Read |
list-citations | The sources (URLs and domains) cited by AI answers, newest first, each flagged when it is your own domain or a competitor’s. | website_id, provider, range_days, since, limit | Read |
Mentions
How mentions are detected and scored in the app.
Citations
Which sources the engines cite when they answer.
Answer gap
| Tool | What it returns | Key parameters | Access |
|---|---|---|---|
list-answer-gaps | Prompts where competitors are named but your brand is not, the highest-leverage visibility gaps to fix. Each gap carries first_seen and an is_new flag, so you can surface only newly opened gaps. | website_id, range_days, limit | Read |
Answer gap
How gaps are identified and how to close them.
Crawler
Analytics on how AI bots crawl, cite, and drive clicks to your site.| Tool | What it returns | Key parameters | Access |
|---|---|---|---|
get-crawler-analytics | The Discovered to Crawled to Cited to Clicked funnel, which AI bots visit (each tagged as training, search index, or live user-browse), AI-referral clicks with top referrers and countries, pages crawled but never cited, cited-but-stale pages, errored crawls, and the robots.txt verdict per AI bot. | website_id, range_days | Read |
list-crawler-pages | Page-level crawl activity: each path with its visit count, last-crawled date, and last HTTP status, most-visited first. | website_id, range_days, limit | Read |
Crawler analytics
The crawl-to-click funnel and what each stage means.
Community and social
The wider web that feeds AI answers: cited community threads and social-listening conversations.| Tool | What it returns | Key parameters | Access |
|---|---|---|---|
list-community-sources | Community and user-generated threads (Reddit, Hacker News, Quora, Stack Overflow, YouTube) that AI answers cite, with brand and competitor flags and sentiment. | website_id, source_type, subject (you, competitor, or both), range_days, limit | Read |
list-source-gaps | Community threads that AI cites which mention competitors but not your brand, ranked as places to go engage. | website_id, range_days, limit | Read |
list-social-mentions | Social-listening mentions of your brand or competitors from Reddit, Hacker News, and Bluesky, with sentiment, relevance, and whether an AI answer already cites the thread. | website_id, source (reddit, hackernews, bluesky), subject (you or competitor), sentiment, min_relevance, since, range_days, limit | Read |
On
list-social-mentions, since is a discovery cursor over when a mention was found, while range_days is a window over when the conversation was posted. They answer different questions, so they filter different fields.Sources
Community threads AI cites for your brand.
Listening
Native social listening across Reddit, Hacker News, and Bluesky.
Websites
| Tool | What it returns | Key parameters | Access |
|---|---|---|---|
list-websites | The websites you can access, with their IDs, domains, workspaces, and which one is currently selected. | None | Read |
Guided prompts
Alongside tools, the server ships two MCP prompts: ready-made instructions your client can run that chain several tools together for you. They are workflows, not data, so they never change anything on their own. Both take an optionalwebsite_id argument and default to your current website.
improve-my-aeo
improve-my-aeo
Analyses your visibility data and suggests concrete improvements to your site. It calls
get-brand-profile, list-answer-gaps, list-mentions, and list-citations, inspects your site’s content where the client can see it, and produces a prioritised list of specific changes (new or rewritten pages, FAQs, comparison content, metadata, internal links), each tied to a real answer gap or under-cited topic.Argument: website_id (optional).draft-prompts
draft-prompts
Proposes new tracked prompts to add. It calls
get-brand-profile and list-prompts to avoid duplicates, then list-answer-gaps to find weak spots, and drafts 8 to 15 realistic prompts a real buyer would ask, grouped by intent. It then asks which to create and, for each you approve, calls create-prompt.Argument: website_id (optional). Creating the approved prompts needs a read & write token.Connect a client
Set up the MCP server, pick a token type, and start calling these tools.