Tools

The AIclicks MCP server exposes one tool per public /api/v1/* endpoint. Every tool is read-only and forwards your API key on every call.

Tools are auto-discovered by the client — there's no manual registration. Once connected, your assistant lists them via the standard MCP tools/list call. The reference below mirrors what your assistant sees.

Account

validate_key

Confirm the API key works. Returns the team it's bound to, the allowed-domains scope, and the per-minute rate limit. No parameters.

list_domains

List every tracked domain your API key can access.

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

Master key: returns an array of teams, each {team_id, team_name, domains: […]} — use team_name to attribute a domain to its team. If an item has a domains array you got the grouped (master) shape; otherwise items are domains directly. Start every session with this call.

Catalog

list_prompts

Paginated list of tracked prompts under a domain. Useful for "show me the queries we monitor for example.com."

Params: domain_id, page (default 1), size (default 25, max 100), topic_id (optional filter).

list_fanout_queries

The discovery-stage expanded query set — fan-out queries the LLMs actually asked when probing a prompt. Helps debug "why did my prompt return this answer?"

Params: domain_id, days (default 30, 1–365), model (default all).

Time-series

All time-series tools share the same shape: { data: { items: [{date, value}] }, generated_at }. Days are snapped to 7d, 30d, or 90d buckets server-side.

get_visibility_time_series

Daily visibility share for the domain — the percentage of monitored prompts where the brand was mentioned.

Params: domain_id, days (default 30).

get_mentions_time_series

Raw mention count per day across all monitored prompts.

Params: domain_id, days (default 30).

get_citability_time_series

Citation-eligibility ratio per day — what fraction of brand mentions came with a citation back to your domain.

Params: domain_id, days (default 30).

get_citations_time_series

Raw citation count per day — outbound links pointing to your domain across AI search results.

Params: domain_id, days (default 30).

Citations & rankings

get_citations

URL-level citation view: every page the domain appears in across AI search results over the window, with citation frequency, aggregate mention count, prompt count, models that cited it, and first/last seen dates. Sorted by frequency desc.

Params: domain_id, days (default 30).

get_brand_rankings

Current share-of-voice ranking for the domain vs. its tracked competitors. One flat list with is_brand: true on your row and false on each competitor.

Params: domain_id, days (default 30).

get_model_leaderboard

Per-channel performance: visibility and average position broken out by AI channel (ChatGPT, Claude, Perplexity, Gemini…). Sorted by visibility desc.

Params: domain_id, days (default 30).

Sentiment

How AI answers feel about the brand and what drives it. Every sentiment tool takes an optional model filter — pass a generic channel name (ChatGPT, Perplexity, Gemini, AI Overviews, Claude…) or leave it all.

get_sentiment_overview

Positive vs. negative split for how LLMs talk about the brand, plus total mentions across the window. Best for "how do AI answers feel about us right now?"

Params: domain_id, days (default 30), model (default all).

get_sentiment_time_series

Daily positive-sentiment percentage — the share of each day's themes that are positive. Shows whether sentiment is trending warmer or colder.

Params: domain_id, days (default 30), model (default all).

list_sentiment_themes

The named themes AI answers raise, each tagged positive or negative with an occurrence count. Sorted by occurrences desc — the *names may be non-English; classifyon the sentiment field.

Params: domain_id, days (default 30), model (default all).

get_sentiment_theme_sources

The URLs cited when those themes were raised, rolled up by citation frequency — which pages shape how LLMs describe the brand. `modehannel names.

Params: domain_id, days (dall).

Error contract

Every tool returns the same envelope as the underlying REST endpoint. On failure the assistant sees a structured error — most commonly:

See Troubleshooting for fixes.