Concepts

Five concepts explain almost every Mentionable MCP response. Read this once and the tool reference stops being cryptic.

What is a fan-out query?

A fan-out query is a web search that an LLM issues internally while answering a user prompt. ChatGPT, Perplexity, Gemini and others rarely answer from memory alone — they issue 3 to 10 search calls to ground the response. Each search call has a query string, a list of URLs returned, and a result the LLM may or may not cite.

Mentionable captures every fan-out query for every tracked prompt, on every LLM, on every daily run. The list_fan_outs tool deduplicates across LLMs and runs, ranks by frequency, and links each query to the originating prompts and LLMs.

Why this matters. Fan-out queries are the cleanest signal of what the LLMs actually search for when your audience asks a question. They beat keyword research because they come from real LLM behavior, not from search-volume estimates. Use them as the input to content briefs, backlink targets and competitor analysis.

Citations vs sources

Mentionable splits the URL surface into three categories:

Category	Where it comes from	What it tells you
Visible citation	A clickable link inside the LLM response.	This domain is part of the answer the user reads. High value.
Hidden citation	A URL referenced internally by the LLM but not surfaced as a link.	The LLM weighted this source. Medium value.
Fan-out source	A URL returned by the search step, used or not.	This domain ranks for the query. Use it for backlink discovery.

The list_llm_sources tool returns all three counts per domain. Filter by appearanceTypes to focus on one category.

Brand mentions vs competitor mentions

A brand mention is a reference to your project's brand (or one of its aliases) in an LLM response. A competitor mention is a reference to a competing brand. Both are stored on PromptResult and rolled up by tool:

• list_prompts returns mention rate (your brand) per prompt and per LLM.
• list_competitors returns mention totals (competitors) per LLM with Share of Voice.
• list_competitor_sources returns the domains where a given competitor is cited.

A prompt can produce zero, one or many brand mentions per LLM run. The MCP exposes raw counts and ratios, not aggregated scores, so you can recompute KPIs in your agent.

Personas

A persona is a profile attached to a tracked prompt that changes how Mentionable simulates the prompt across LLMs. Examples: independent SEO consultant, marketing manager at a B2B SaaS, graduate student in finance. The persona is injected into the LLM call to mimic the variation real users would see.

In the MCP, personas appear as:

• A personaIds filter on list_prompts.
• A persona field on each prompt in the response.

Personas are project-scoped. They are managed in the dashboard, not via the MCP.

Scopes and access control

Three layers gate every MCP call:

1. Tenant — the workspace. Every project belongs to one tenant.
2. Workspace member — the user behind the API key. A member has a role (owner, admin, member, customer) and an optional project whitelist.
3. API key — owned by a member, with an optional further project whitelist.

The effective project scope is the intersection of member scope and key scope. Read tools require any non-customer role to be present. Write tools (bulk_update_competitor_status) reject customer.

A call against a project outside the effective scope returns 403 FORBIDDEN — Project not in API key scope. A call against a project in scope but missing in the database returns Project not found (the lookup never confirms cross-tenant existence).

Cursors and pagination

Every list tool uses cursor-based pagination:

{
  "data": [/* up to limit items */],
  "pageInfo": {
    "hasMore": true,
    "nextCursor": "clxyz123",
    "totalCount": 247
  }
}

To fetch the next page, pass the nextCursor value as cursor in the next call. nextCursor is null when there are no more pages. The default limit is 20, max 100.

totalCount is the count after filters. It is the right field to display "X results" in your agent UI. Pagination counts as one MCP request per page against the rate limit.

Cost model

Mentionable MCP calls do not consume scan credits or AI credits. They are bounded only by the 100-request-per-minute rate limit. Scan credits apply to the daily tracking pipeline (one credit per prompt × LLM × day on the Agency plan). AI credits apply to article generation and audits inside the dashboard. The MCP is included in every paid plan at no extra cost.