Tools

The AIclicks MCP server gives one tool for each public /api/v1/* endpoint. It sends your API key with each call. Most tools only read data. The write tools change your account. See Write / manage.

Your MCP client finds the tools automatically. You do not register them. After you connect, your assistant lists them with the standard MCP tools/list call. This page shows the same tools.

Common parameters

Many tools use these optional parameters. Each tool below lists the parameters that it accepts.

On this page, period means days, start_date and end_date.

Account

validate_key

Checks that the API key works. Returns the team of the key, the allowed domains and the rate limit per minute. It has no parameters.

list_domains

Lists all tracked domains that your API key can access.

Team key: returns a flat list of {id, name, website, …}.

Master key: returns a list of teams. Each team is {team_id, team_name, domains: […]}. Use team_name to find the team of a domain. If an item has a domains list, you have the master shape. If not, the items are domains. Start each session with this call.

get_domain_status

Shows the status of the analysis of a domain. It returns these fields:

• analysis_complete: no analysis runs now.
• has_any_completed_analysis: one analysis is complete, so the analytics tools return data.
• responses_count and queries_count: the progress of a running analysis.
• is_discovery_ready: competitor discovery has candidates.

The result is not cached. A first analysis takes tens of minutes. Check a new domain every few minutes.

Params: domain_id.

get_team_usage

Shows the plan of a team and how much of it is used. It includes prompt credits (limit, used, remaining), domains, AI models, price and features. If you give domain_id, it also shows the tracked prompts and competitor slots of that brand. Use it before you add many prompts or competitors.

Params: team_id, domain_id (optional).

Prompts and catalog

list_prompts

Lists the tracked prompts of a domain, with their topics and tags, page by page. For the metrics of each prompt, use list_prompt_metrics.

Params: domain_id, page (default 1), size (default 50, max 500), q (text search), topic_ids, tag_ids, fresh.

list_tags

Lists the tags of a domain, each with its UUID, name and number of prompts. Use it to find the tag_ids that other tools need. To make a new tag, use create_tag.

Params: domain_id.

list_topics

Lists the topics of a domain, each with its UUID and name. Use it to find the topic_ids that other tools need. To make a new topic, use create_topic.

Params: domain_id.

list_prompt_metrics

Lists all tracked prompts with their metrics for the period. The metrics are visibility (%), mentions, citations, avg_position, responses and estimated_search_volume. Each row also has topics and tags. Prompts with no answers show zeros. Use it to find the weakest prompts.

Params: domain_id, period, model, topic_ids, tag_ids, sort_by (visibility is the default, mentions, citations, avg_position, responses, estimated_search_volume), sort_dir, page, size (default 100, max 500).

get_prompt_statistics

Shows how each prompt performs over time. It returns one page of prompts, sorted by sort. Each prompt has its estimated_search_volume and totals for the period. It also has a daily series of mentions, responses, citations and avg_position. Use it to find the prompts that went up or down most.

Params: domain_id, period, model, topic_ids, tag_ids, sort (mentions is the default, visibility, position, responses), order, page, limit (default 25, max 100) or size (max 500).

get_prompt_brands

Lists all tracked brands for one prompt. Your brand is first, then each tracked competitor. Each brand has total_mentions, avg_visibility, avg_sov, avg_position and avg_sentiment. Use it to find the brand that wins a prompt.

Params: domain_id, prompt_id, period, model.

get_answers

Lists the AI answers for one prompt, newest first. Each answer has the date, the model and the answer text. It also shows if and where your brand is named, the tracked competitors with their positions, and the cited URLs. Use it to read what the AI said.

Params: domain_id, prompt_id, period, model, page, size (default 20, max 100).

get_topic_metrics

Gives a scorecard for each topic. The scorecard has prompts, answers, avg_visibility, total_mentions, avg_position, citation_count, brand_citation_count, avg_sentiment and avg_volume. Use it to find strong and weak topics.

Params: domain_id, period, model.

get_tag_metrics

Gives the same scorecard for each tag. Use it to compare groups of prompts, for example branded and non-branded.

Params: domain_id, period, model.

list_fanout_queries

Lists the fan-out queries that the AI engines ran to answer your prompts. The queries are grouped by prompt. Use it to find why a prompt got an answer.

Params: domain_id, period, model, prompt_id (one prompt), include_urls (adds cited_urls to each query), page, size (default 100, max 500), fresh. For a large project, give page=1 or prompt_id.

Time series

All time-series tools return { data: { items: [{date, value, …}] }, generated_at }. Each day also has answers_count. This is the number of analyzed answers for the value.

get_visibility_time_series

Gives the daily visibility. Visibility is the share of tracked AI answers that mention the brand.

Params: domain_id, period, model, topic_ids, tag_ids, fresh.

get_mentions_time_series

Gives the number of brand mentions for each day.

Params: domain_id, period, model, topic_ids, tag_ids, fresh.

get_citability_time_series

Gives the daily share of all citations that go to your domain.

Params: domain_id, period, model, topic_ids, tag_ids, fresh.

get_citations_time_series

Gives the number of citations to your domain for each day.

Params: domain_id, period, model, topic_ids, tag_ids, fresh.

Citations

get_citations

Lists each page that AI answers cite for your prompts, sorted by frequency. Each URL has these fields:

• page type, citation frequency, mentions and prompt count
• prompt_ids and models
• mentioned: the page names your brand
• competitors: the tracked competitors that the page names

A summary block divides the citations into pages that mention your brand and pages that do not.

Pagination is optional. If the period is more than 7 days, give page=1. If you do not, the response can be too large.

Params: domain_id, period, model, topic_ids, tag_ids, cited_domain, page_type, min_frequency, is_brand_owned, mentioned, group_by (domain or page_type), page, size (default 200, max 1000), fresh.

get_citation_domains

Lists the cited hosts, sorted by citations. Each host has citations, prompt_count, share_percent and owner. The owner is own, competitor or third_party. Use it to see which sites the AI cites and how many are yours. For the URLs of one host, use get_citations(cited_domain=…).

Params: domain_id, period, topic_ids, tag_ids, page, size (default 100, max 500), fresh.

get_competitor_citations

Shows how often AI answers cite each tracked domain. Your brand is first, then each competitor. Each entry has citations and share_of_all_citations (%). Use it to find the website that LLMs cite most.

Params: domain_id, period, model, topic_ids, tag_ids.

get_citation_share

Gives the same share for each topic or each tag in one call. Use it to find the topics where competitors get more citations than you.

Params: domain_id, period, model, group_by (topic is the default, or tag).

Competitors and rankings

get_brand_rankings

Ranks your brand and the tracked competitors by share of voice. Each row has mentions, visibility, sov, avg_position, prompts_mentioned and answers_count. Your row has is_brand: true.

Params: domain_id, period, model, topic_ids, tag_ids, fresh.

get_competitor_time_series

Gives the trend of get_brand_rankings. Your brand is first, then the competitors. Each entry has averages and totals for the period. It also has a daily series of {visibility, sov, mentions, avg_position, sentiment, answers_count, citations, citation_count, citability}. Use it to see the trend of a competitor against your brand.

Params: domain_id, period, model, topic_ids, tag_ids, fresh.

get_competitor_discovery

Lists brands that AI answers name for your prompts, but that you do not track. They are sorted by prompts_mentioned out of total_prompts. Use it to find new competitors to track.

Params: domain_id, days.

list_competitors

Lists the competitors of a domain, sorted by name. By default, it returns the tracked competitors. If is_dedicated=false, it returns the discovered brands that you do not track. If null, it returns both. The discovered list can be long, so give page=1.

Params: domain_id, is_dedicated (default true), active, page, size (default 100, max 500), fresh.

get_model_leaderboard

Gives the visibility and average position for each AI channel. Each row has answers_count. Rows are sorted by visibility.

Params: domain_id, period.

Sentiment

These tools show how AI answers describe the brand, and why.

get_sentiment_overview

Gives the positive and negative split and the total mentions for the period.

Params: domain_id, period, model.

get_sentiment_time_series

Gives the daily positive percentage. This is the share of the themes of each day that are positive.

Params: domain_id, period, model.

list_sentiment_themes

Lists the themes that AI answers mention. Each theme is positive or negative and has an occurrence count. Theme names can be in other languages. Use the sentiment field to classify them.

Params: domain_id, period, model.

get_sentiment_theme_sources

Lists the URLs that AI answers cite for these themes. Each URL has its domain, its frequency, its themes and the models that cite it. Use it to find the pages that change how LLMs describe the brand.

Params: domain_id, period, model.

get_sentiment_answers

Lists the AI answers for one sentiment theme. Each answer has the channel, prompt, date, the quoted answer text and the cited URLs. Use it to show the evidence for a theme.

Params: domain_id, theme_id (from list_sentiment_themes), model, page, size (default 10, max 50).

Engage

list_engage_recommendations

Lists community threads and posts that AI answers use for your prompts. You can reply to them to improve your visibility. Each row has these fields:

• the URL, title and platform
• frequency: how often AI answers cite it
• metrics: engagement data
• the status
• is_brand_named: true if the page names your brand, false if not, null if not checked

The response also has counts_by_platform.

Params: domain_id, platform (reddit, x, linkedin, quora, …), status (pending, done, dismissed), prompt_ids, topic_ids, min_engagement and min_comments (both need platform), sort_by (frequency is the default, engagement, comments), sort_dir, page, size (default 50, max 100).

ChatGPT ads

These tools show the ads in ChatGPT answers for the prompts of the domain. All tools take domain_id and the period.

get_chatgpt_ads_kpis

Gives the main metrics: prompts with ads, brand appearances, unique advertisers and total ad cards. Each metric has a change against the previous period of the same length.

get_chatgpt_ads_leaderboard

Lists the brands that advertise on ChatGPT for your prompts, sorted by prompt coverage.

get_chatgpt_ads_timeline

Gives the daily ChatGPT ad activity for the period.

get_chatgpt_ads_prompts

Lists the tracked prompts that show ChatGPT ads. It also takes page (default 1) and per_page (default 50, max 500).

get_chatgpt_ads_cards

Lists each ad card, with its creative and advertiser. It also takes page and per_page.

GA4 / LLM traffic

These tools show the site traffic that AI assistants send to the brand. The data comes from the Google Analytics 4 property of the brand. Each tool takes domain_id, the period and an optional llm_source (chatgpt, perplexity, claude, gemini, copilot, …). If the domain has no GA4 connection, the tools return empty data, not an error.

get_ga4_summary

Gives the total sessions, users and pageviews from AI assistants, and the totals of the previous period.

get_ga4_by_llm

Gives the same totals for each LLM source, and the previous period. Use it to find the assistants that send visitors.

get_ga4_timeline

Gives the daily sessions from AI assistants, divided by LLM source.

get_ga4_top_pages

Lists pages, sorted by sessions from AI assistants.

get_ga4_top_locations

Gives the sessions from AI assistants for each country.

get_ga4_top_browsers

Gives the sessions from AI assistants for each browser (top 10).

get_ga4_devices

Gives the sessions from AI assistants for each device category.

get_ga4_key_events

Gives the key events (conversions) from AI traffic: the total, the total for each LLM and the top events. It also gives the total of the previous period.

Write / manage

These tools change your account. Your assistant must ask you before it calls them. Unless the text says something different, each tool needs these conditions:

• You are a member of the team of the domain.
• The team has a Pro+ plan. If not, the tool returns 403.

Tag changes need the admin, co-admin or editor role. New items can take up to ~30 minutes to show in the dashboard, because the dashboard uses a cache.

create_domain

Makes a new brand (domain) with prompts. The analysis starts immediately. The team's domain limit applies. Give a prompts list, or set generate_prompts=true. With generate_prompts=true, the server selects the prompts and you cannot review them first. A brand with no prompts is rejected. To know when the first analysis is complete, use get_domain_status.

Params: team_id, name, website, country, language (ISO code), states and cities (geo IDs), prompts (list of {text, topics?, tags?}), generate_prompts (default false), is_pitch. A pitch brand is a 7-day brand for agencies. It has a maximum of 25 prompts and uses a pitch credit.

add_prompt

Adds one tracked prompt. It uses one prompt credit. It returns an error if the prompt exists or if the team has no credits.

Params: domain_id, text, topic_ids, tag_ids. If you omit tag_ids, the default tags are added. If you give [], no tags are added.

add_prompts

Adds up to 100 prompts in one call. Give topics and tags by name. The server makes unknown topics. The server ignores unknown tags. Duplicate prompts show under duplicates. Other failures show under errors. If the team does not have sufficient credits, the full call fails.

Params: domain_id, prompts (list of {text, topics?, tags?}).

update_prompt

Changes the text of a prompt. It can also change its topics and tags.

Params: domain_id, prompt_id, text (max 500 characters), topic_ids (replaces all topics; [] removes all), add_tag_ids, remove_tag_ids.

archive_prompts

Stops tracking up to 100 prompts. Each archived prompt gives back one credit. The past results stay. If one ID is not an active prompt of the domain, no prompt is archived.

Params: domain_id, prompt_ids.

set_prompt_tags

Adds or removes tags on up to 100 prompts. Tags that you do not list do not change.

Params: domain_id, prompt_ids, add_tag_ids, remove_tag_ids.

set_prompt_topics

Replaces the topics of one prompt.

Params: domain_id, prompt_id, topic_ids ([] removes all).

create_tag

Makes a tag. It returns an error if the name exists.

Params: domain_id, name (max 60 characters), color_id (slate is the default, gray, blue, amber, red, orange, green, teal, indigo, purple, pink).

create_topic

Makes a topic. It returns an error if the name exists.

Params: domain_id, name, description (optional).

add_competitor

Starts to track one competitor. By default, the competitor goes on the tracked (dedicated) list. This list counts against the competitor limit of the plan. It returns an error if an active competitor has that website, or if the limit is full. If you add a removed competitor again, it becomes active again.

Params: domain_id, competitor_domain, competitor_name, is_dedicated (default true; use false for a passive entry), competitor_variations.

add_competitors

Tracks up to 50 competitors in one call. Give a competitors list, or give from_discovery=N to track the top N discovery candidates. Before you use from_discovery, make sure that get_domain_status shows is_discovery_ready. The server does not make duplicates. It changes existing entries to tracked. It stops when the limit is full. It returns added, promoted, skipped (with reasons) and remaining_slots.

Params: domain_id, competitors (list of {competitor_domain, competitor_name, competitor_variations?}) or from_discovery (1–50).

update_competitor

Changes a competitor. You can change its name and its name variations. You can pause or resume it. You can put it on the tracked list or remove it from the list. Only the fields that you give change. If you make it dedicated and active, the server checks the limit.

Params: competitor_id (from list_competitors), competitor_name, competitor_variations (replaces all; [] removes all), active, is_dedicated.

Errors

Each tool returns the same envelope as the REST endpoint. If a call fails, the assistant gets a structured error. The most frequent errors are:

For solutions, see Troubleshooting.