MCP tools reference — BrandAxis docs

The BrandAxis MCP server has 13 read-only tools. Your assistant chooses and calls them for you, so you don’t need this page to use the MCP. It’s here for anyone who wants to know exactly what the assistant can read, or who is building on it.

Each tool is a BrandAxis API endpoint with the same name, parameters and answer. For response fields, see the API reference.

Conventions

Start with listWorkspaces. Most tools take a workspace id as id.
Dates are days in YYYY-MM-DD format in the workspace’s timezone, and to is inclusive. Without from and to the range is the last 7 days. A range can be at most 366 days.
Multi-value filters (models, prompts, topics, tags, brands, countries) take comma-separated ids. dimensions takes a list.
Paging uses limit and offset.
Figures match the BrandAxis dashboard.

A typical flow:

listWorkspaces
  → listPrompts / listBrands / listTopics / listTags
  → listModels
  → listChats / reports / sources
  → getChat / getPageContent for detail

Model ids

Use these values in the models filter. listModels returns the current list.

id	Name	Kind
`ChatGPT-5`	ChatGPT	UI
`AI Overview`	Google AI Overviews	UI
`AI Mode`	Google AI Mode	UI
`Perplexity`	Perplexity	UI
`Gemini`	Gemini	UI
`Copilot`	Microsoft Copilot	UI
`Claude Sonnet`	Claude Sonnet	API

UI models are measured from the real AI search interfaces. API models are measured from the model’s API. See which models we track.

Tools

`listWorkspaces`

The workspaces your key can see. A workspace is one brand being tracked, with its prompts, competitors and settings. Start here to get the ids the other endpoints need.

No parameters.

listWorkspaces({})

`listPrompts`

The questions the workspace asks the AI models every day. Prompts suggested on the Prompts page, which do not run until accepted, are listed with status=suggested.

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Workspace id
`status`	string	No	default `active`; `active`, `suggested`, `all`	`active` prompts run every day; `suggested` prompts are offered on the Prompts page and do not run until accepted.

listPrompts({ id: "<workspace-id>", status: "active" })

`listBrands`

Your brand and the competitors tracked beside it. Suggestions the system found but you have not accepted are unconfirmed; an alias is listed under its brand, never as a row.

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Workspace id
`status`	string	No	default `confirmed`; `confirmed`, `unconfirmed`, `rejected`, `all`	Brand status filter.

listBrands({ id: "<workspace-id>", status: "confirmed" })

`listTopics`

The topics prompts are sorted into. Use their ids in topics to narrow other requests.

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Workspace id

listTopics({ id: "<workspace-id>" })

`listTags`

The tags prompts are labeled with. Use their ids in tags to narrow other requests.

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Workspace id

listTags({ id: "<workspace-id>" })

`listChats`

The AI answers collected in a date range, one per prompt per model per day, newest first. Filter to answers that name a brand, do not name it, or cited a given site/page.

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Workspace id
`from`	string (date)	No	—	First day of the range. Default: 6 days before `to`; day is interpreted in the workspace timezone.
`to`	string (date)	No	—	Last day of the range, inclusive. Default: today. At most 366 days from `from`; day is interpreted in the workspace timezone.
`models`	string	No	—	Comma-separated model ids, e.g. `ChatGPT-5,Perplexity`.
`prompts`	string	No	—	Comma-separated prompt ids.
`topics`	string	No	—	Comma-separated topic ids; keeps prompts in any of the topics.
`tags`	string	No	—	Comma-separated tag ids; keeps prompts with any of the tags. With `topics`, both filters must hold.
`brand`	string (uuid)	No	—	A brand id: answers that name it or one of its aliases.
`mentioned`	string	No	default `yes`; `yes`, `no`	Needs `brand`. `no` keeps answers that do not name the brand.
`domain_id`	string (uuid)	No	—	Answers that cited that site.
`url_id`	string (uuid)	No	—	Answers that cited that page.
`include`	string	No	`response`	`response` adds each answer’s text. Answers are long, so a page is then 10 answers by default and at most 25.
`limit`	integer	No	default `100`; 1–1000	Number of rows to return. With `include=response`: 10 by default, at most 25.
`offset`	integer	No	default `0`; min 0	Number of rows to skip. Use it to get the next page.

When include=response is used, pagination limits are tighter: default 10, maximum 25.

listChats({ id: "<workspace-id>", from: "2026-10-01", to: "2026-10-16", models: "ChatGPT-5,Perplexity", include: "response", limit: 25 })

`getChat`

One answer in full: its text, the brands it names with their position and sentiment, and the pages it cited.

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Chat id

getChat({ id: "<chat-id>" })

`getPageContent`

The text of a page an answer cited, as markdown, stored when the page was cited. Get page ids from a kind=urls source or an answer’s sources. markdown can be null when the page could not be read (for example, automated-access blocks or JavaScript-rendered text).

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Page id (`id` of a `kind=urls` source)

getPageContent({ id: "<page-id>" })

`getBrandReport`

The brand report behind the dashboard: how often each brand is named, where it ranks, how it is spoken of, and how often it comes first. Supports breakdowns by model, prompt, topic, tag, country, date, week or month; previous-period comparison; and top-N selection.

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Workspace id
`from`	string (date)	No	—	First day of the range. Default: 6 days before `to`; day is interpreted in the workspace timezone.
`to`	string (date)	No	—	Last day of the range, inclusive. Default: today. At most 366 days from `from`; day is interpreted in the workspace timezone.
`models`	string	No	—	Comma-separated model ids, e.g. `ChatGPT-5,Perplexity`.
`prompts`	string	No	—	Comma-separated prompt ids.
`topics`	string	No	—	Comma-separated topic ids; keeps prompts in any of the topics.
`tags`	string	No	—	Comma-separated tag ids; keeps prompts with any of the tags. With `topics`, both filters must hold.
`dimensions`	array[string]	No	`model`, `prompt`, `topic`, `tag`, `country`, `date`, `week`, `month`	One row per group of these dimensions. With none, the whole range is one group.
`countries`	string	No	—	Only prompts in these countries: comma-separated two-letter codes, e.g. `ZA,US`.
`status`	string	No	default `confirmed`; `confirmed`, `unconfirmed`, `rejected`, `all`	Which brand statuses the report includes.
`brands`	string	No	—	Only these brands. With `top`, explicitly selected brands are added to the top ones. Comma-separated brand ids.
`top`	integer	No	1–100	Keep only the first N brands by `order` over the whole range, then break them down by the requested dimensions.
`compare`	string	No	`previous`	Adds `previous` to every row for the immediately preceding window of the same length.
`order`	string	No	default `position`; `position`, `visibility`, `mentions`, `share_of_voice`, `rank`, `sentiment`, `wins` (+ `.asc` / `.desc`)	Order rows within a group. Add `.asc` or `.desc` to set direction.
`limit`	integer	No	default `1000`; 1–5000	Number of rows to return.
`offset`	integer	No	default `0`; min 0	Number of rows to skip. Use it to get the next page.

Every brand has a row in every group, including zero-valued rows.
With the tag dimension, an answer is counted under each tag of its prompt (restricted to tags if supplied). Untagged prompts appear under tag: null.
With the country dimension, an answer belongs to its prompt’s current country.
A report that would exceed 20,000 rows (groups × brands) is refused before execution.
Rows are ordered by dimensions in turn, earliest first, then by order. A group with no answers has no row.
compare=previous returns previous_from and previous_to. On date/week/month rows, previous is the bucket in the same position of the prior window. Missing prior groups use chats: 0.

getBrandReport({ id: "<workspace-id>", from: "2026-10-01", to: "2026-10-16", dimensions: ["model"], compare: "previous", order: "visibility.desc" })

`getSourceReport`

The sites (kind=domains) or pages (kind=urls) cited by answers: how many answers cited each, how often, source type, and—when a brand is supplied—whether its pages name that brand. Supports report-style breakdowns and comparison.

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Workspace id
`from`	string (date)	No	—	First day of the range. Default: 6 days before `to`; day is interpreted in the workspace timezone.
`to`	string (date)	No	—	Last day of the range, inclusive. Default: today. At most 366 days from `from`; day is interpreted in the workspace timezone.
`models`	string	No	—	Comma-separated model ids, e.g. `ChatGPT-5,Perplexity`.
`prompts`	string	No	—	Comma-separated prompt ids.
`topics`	string	No	—	Comma-separated topic ids; keeps prompts in any of the topics.
`tags`	string	No	—	Comma-separated tag ids; keeps prompts with any of the tags. With `topics`, both filters must hold.
`kind`	string	No	default `domains`; `domains`, `urls`	`domains` returns sites; `urls` returns pages.
`dimensions`	array[string]	No	`model`, `prompt`, `date`, `week`, `month`	One row per group of these dimensions. With none, the whole range is one group.
`types`	string	No	—	Comma-separated source types exactly as returned in `type`, e.g. `Editorial,Corporate`. Case-sensitive.
`domain_id`	string (uuid)	No	—	Only one site. With `kind=domains`, covers just that site; with `kind=urls`, just that site’s pages.
`url_id`	string (uuid)	No	—	Only one page. Requires `kind=urls`.
`search`	string	No	—	Only sites or pages whose address contains this text. Case-insensitive.
`brand`	string (uuid)	No	—	A brand id. Each row then says whether the source names that brand (`mentioned`).
`mentioned`	string	No	`yes`, `no`, `unknown`	Needs `brand`. Keeps only sources with this `mentioned` value.
`top`	integer	No	1–100	Keep only the first N sources by `order` over the whole range, then break them down by dimensions.
`compare`	string	No	`previous`	Adds `previous` metrics for the immediately preceding window of the same length.
`order`	string	No	default `chats`; `chats`, `citations`, `rating` (+ `.asc` / `.desc`)	Order rows within a group. Add `.asc` or `.desc` to set direction.
`include`	string	No	`mentioned_brands`	`mentioned_brands` adds confirmed brands named on each source’s pages. Slower; request only when needed.
`limit`	integer	No	default `1000`; 1–5000	Number of rows to return.
`offset`	integer	No	default `0`; min 0	Number of rows to skip. Use it to get the next page.

A source has no row in a group where nobody cited it.
Rows are ordered by dimensions in turn, earliest first, then by order.
compare=previous follows the same previous-window semantics as the brand report.

getSourceReport({ id: "<workspace-id>", kind: "domains", top: 20, order: "chats.desc" })

`getSourceTypesReport`

Per source type, returns how many answers cited at least one source of that type—the dashboard’s source-type pie chart. Most-cited types appear first within a group.

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Workspace id
`from`	string (date)	No	—	First day of the range. Default: 6 days before `to`; day is interpreted in the workspace timezone.
`to`	string (date)	No	—	Last day of the range, inclusive. Default: today. At most 366 days from `from`; day is interpreted in the workspace timezone.
`models`	string	No	—	Comma-separated model ids, e.g. `ChatGPT-5,Perplexity`.
`prompts`	string	No	—	Comma-separated prompt ids.
`topics`	string	No	—	Comma-separated topic ids; keeps prompts in any of the topics.
`tags`	string	No	—	Comma-separated tag ids; keeps prompts with any of the tags. With `topics`, both filters must hold.
`kind`	string	No	default `domains`; `domains`, `urls`	`domains` returns sites; `urls` returns pages.
`dimensions`	array[string]	No	`model`, `date`, `week`, `month`	One row per group of these dimensions. With none, the whole range is one group.
`domain_id`	string (uuid)	No	—	Requires `kind=urls`. Restricts the report to pages from this site.
`compare`	string	No	`previous`	Adds `previous` metrics for the immediately preceding window of the same length.

Uses the same group ordering and previous-window comparison semantics as the other report tools.

getSourceTypesReport({ id: "<workspace-id>", kind: "domains", dimensions: ["model"] })

`listSources`

The Sources page’s own list, as shown in BrandAxis: sites or pages cited in a range, most cited first. Fields correspond to the sources report.

Parameter	Type	Required	Default / allowed	Description
`id`	string (uuid)	Yes	—	Workspace id
`from`	string (date)	No	—	First day of the range. Default: 6 days before `to`; day is interpreted in the workspace timezone.
`to`	string (date)	No	—	Last day of the range, inclusive. Default: today. At most 366 days from `from`; day is interpreted in the workspace timezone.
`models`	string	No	—	Comma-separated model ids, e.g. `ChatGPT-5,Perplexity`.
`prompts`	string	No	—	Comma-separated prompt ids.
`topics`	string	No	—	Comma-separated topic ids; keeps prompts in any of the topics.
`tags`	string	No	—	Comma-separated tag ids; keeps prompts with any of the tags. With `topics`, both filters must hold.
`kind`	string	No	default `domains`; `domains`, `urls`	`domains` returns sites; `urls` returns pages.
`domain_id`	string (uuid)	No	—	Requires `kind=urls`. Restricts results to pages from this site.
`limit`	integer	No	default `100`; 1–1000	Number of rows to return.
`offset`	integer	No	default `0`; min 0	Number of rows to skip. Use it to get the next page.

listSources({ id: "<workspace-id>", kind: "urls", limit: 100 })

`listModels`

The AI models BrandAxis can track, with the ids used by the models filter in other endpoints.

No parameters.

listModels({})

Edge cases

mentioned on listChats and getSourceReport only works with brand.
url_id on getSourceReport needs kind=urls.
domain_id on getSourceTypesReport and listSources needs kind=urls.
getPageContent can return markdown: null when the page couldn’t be read when it was cited (for example, it blocked automated access or its text was rendered by JavaScript).
getBrandReport refuses a report that would have more than 20,000 rows (groups × brands). Narrow the range, the dimensions or the brands.
listChats with include=response returns at most 25 answers a page.

Conventions#

Model ids#

Tools#

listWorkspaces#

listPrompts#

listBrands#

listTopics#

listTags#

listChats#

getChat#

getPageContent#

getBrandReport#

getSourceReport#

getSourceTypesReport#

listSources#

listModels#

Edge cases#