Semantica AI — AI Search Visibility MCP Server

Add a competitor to a project's tracked (starred) competitors list (writes to Semantica tracked_competitors). Provide domain and/or brandVariants (brand name synonyms — alternate spellings/names the AI models might use) — at least one is required. If a competitor with the same domain or brand already exists, it is merged (brandVariants unioned) rather than duplicated.

Bulk-delete prompts from a project. Address each prompt by promptId (from list_project_topics_prompts) or by promptText (add topicId/topicTitle when the same text exists in several topics). Removed prompts stop being scanned; their past scan results stay in history. Max 500 per call; per-prompt failures come back in errors[].

Bulk-delete topics of a project. Deleting a topic also deletes ALL its prompts and their scan history stays orphaned — confirm with the user first. Address topics by topicIds (preferred) and/or topicTitles. Max 100 per call.

Get details of a Semantica project by ID. Response includes effective prompts (queries), trackedCompetitors (favorites), and mentionedSitesAndBrands (domains/brands inferred from scan citations). Semantica staff (admin, team-lead, sales-manager, geo-specialist) can access any project without clientId.

Get competitor data for a project: tracked (starred) competitors and mention-derived sites/brands from scans. Same payload as the competitors block inside get_project, as a dedicated call.

Authoritative Semantica AI project report matching the dashboard: overall and competitor visibility, mention rate by topic, top cited domains overall and by AI provider, and merged top brands. Use this tool for comprehensive client reports instead of recounting raw get_scan citations/results. Domain count = unique domain per AI response (not raw URLs); topic % = mention rate within the topic (not share of all project mentions); linked domains and brand variants are merged for brand/competitor metrics.

Scan schedule of a project: when it was last scanned and when the next scheduled scan runs. Same data as the scan schedule line in the dashboard.

Project settings as in the dashboard: additional domains counted as the brand's own, brand name synonyms, selected AI providers, country/location, site languages and the weekly scan schedule.

List a project's topics with their prompts, tags and locale: per-topic geo/language override plus the effective values after inheriting from the project. Returns topicId and promptId — call this first to get the IDs needed by update_project_topics, delete_project_topics, update_project_prompts and delete_project_prompts. Also returns the project tag dictionary.

Remove a competitor from a project's tracked (starred) competitors list.

Start a scan of an existing project across its topics and prompts — the "Scan" button in the dashboard. Optionally limit it to specific providers. Returns alreadyQueued: true when a scan of this project is already waiting for a slot (no duplicate is created — do not retry, poll get_active_scans instead). The scan runs in the background: follow it with get_active_scans, then read results with get_latest_scan.

Update an existing tracked competitor: brand name, brand variants (synonyms), additional domains, or topic scoping. Only the fields you pass are changed — brandVariants/additionalDomains/topicIds fully replace the existing list (pass the complete desired list, not just the delta).

Bulk-edit prompts: change text, move to another topic, and set tags. Address each prompt by promptId (from list_project_topics_prompts) or by promptText (add topicId/topicTitle when the same text exists in several topics). tags fully REPLACE the prompt's tags (empty array clears them); unknown tag names are created in the project. Changing the text resets that prompt's scan history, same as in the app. Geo and language are not prompt-level — set them per topic with update_project_topics. Max 500 prompts per call; per-prompt failures come back in errors[].

Update project settings. Only the fields you pass are changed; list fields (additionalDomains, brandSynonyms, selectedProviders, siteLanguages) fully REPLACE the current list — pass the complete desired list, not just the delta. Changing additionalDomains or brandSynonyms recalculates mentions over existing scans, so the response may carry a recalculation summary.

Bulk-update topics of a project: rename, change description, set geo location and answer language. Geo and language live on the TOPIC (prompts inherit them): location is a SerpApi canonical location like "Moscow, Russia", siteLanguage is a code like "ru"/"en". Pass null to clear the override so the topic inherits the project settings. Address each topic by topicId (from list_project_topics_prompts) or by its current topicTitle. Max 100 topics per call; per-topic failures come back in errors[] without aborting the rest.

Add a comment to a document, optionally anchored to a quoted fragment. Use it for review notes that a human should act on; to propose a concrete rewrite use add_content_hub_suggestion instead.

Propose a concrete rewrite of a fragment: selectedHtml is the current text, afterHtml is the replacement. The suggestion is not applied until a person accepts it in the dashboard — prefer this over save_content_hub_document when the text is under review.

Create a Content Hub document in a project. Pass the text as contentMarkdown (preferred for agents) or contentHtml. Use create_content_hub_document_from_generation instead when the text came from the built-in blog/HowTo generator — that keeps the link to the generation.

Turn a finished generation (blog article or HowTo) into a Content Hub document — the "Send to Content Hub" action in the dashboard. generationId comes from the generation history.

Remaining monthly quota of a generator (blog, faq, howto have their own). Check it before a batch of runs — the same limit applies in the dashboard.

Comments and suggested edits on a document: thread, anchors to fragments, who wrote what and what is still unresolved.

Get one Content Hub document with its content (HTML and Markdown), status, meta description and publication data.

Version history of a document: who saved what and when, with labels. Use it before overwriting someone else's text.

History of a generator: past runs with topics, status and ids. Use the id with get_blog_generation (full article) or create_content_hub_document_from_generation.

List Content Hub documents of a project — the board in the dashboard. Each item carries status (in_progress → editing → approved → published → cited), title, published URL and update time. Statuses are derived from facts (edits, publication, citations in AI answers), not set by hand.

Move a document between the two manual states: "editing" (edits in progress) and "approved" (edits accepted). The other states — in_progress, published, cited — are derived from facts and cannot be set by hand, exactly as on the dashboard board.

Record where the document was published. The URL starts publication tracking: the document becomes "published" and turns into "cited" once AI answers start citing that page. Pass null to clear it.

AI Commerce: audit a YML product feed (Yandex Goods) for Yandex Commerce Protocol and Alice AI readiness. Deterministic analysis returns a feed score, systemic issues and a list of "bad" product cards (missing pictures, short descriptions, no params, out of stock, no price, etc.); the response also includes an LLM "aiSummary" (verdict, key problems, priority actions). Results are stored in audit history. Provide either feedUrl or feedXml.

AI Commerce: Alice price check from Yandex Market product URLs. Reads price from Market listing, then UI-scans Alice. Async: returns { id, total }; poll ycp_price_check_result. Each URL = 1 price check.

AI Commerce: analyze a Yandex Market product page by URL (market.yandex.ru). UI scan + vision — score, issues (price, description, photos, specs), AI summary. Synchronous. No YML feed required.

AI Commerce: get a saved Yandex Market listing audit by id (from ycp_market_listing).

AI Commerce: start a selective price check of feed products inside Alice AI (UI scan + vision parsing of the shopping block). Compares your price vs competitors shown in Alice and reports where you win/lose. Asynchronous: returns { id, total }; poll ycp_price_check_result with the id. Each product costs 1 scan (usage-based plans are billed accordingly). Provide either feedUrl or feedXml.

AI Commerce: get the status and results of a price check started by ycp_price_check. Status: processing | completed | failed. When completed, returns per-product verdicts (we_win | we_lose | not_shown | no_offers), your price vs the cheapest competitor in Alice, and a summary (wins, losses, average gap, biggest loss).

Google Trends (via Semantica): where a keyword is most popular (0–100 relative interest by region). Optional resolution: COUNTRY, REGION, CITY, DMA.

Google Trends (via Semantica): relative search interest over time (0–100 scale, 100 = peak in period). Use for seasonality and demand dynamics.

Google Trends (via Semantica): related search queries (top + rising) for a seed keyword. Relative interest 0–100. No API key required on Semantica server.

Google Trends (via Semantica): related topics (top + rising) for a keyword. Complements related_queries for semantic expansion.

Dialog: after code + password from user in chat, call this. Semantica AI — registration step 2. The response carries accessToken — the user adds it as Bearer in their MCP settings. Immediately show the returned trial offer, Enterprise and Go options, payment methods and billing link to the user.

Dialog: ask user for email in chat, then call this. Semantica AI — registration step 1: send a 6-digit code to the email. Only without an Authorization header.

Dialog: optional after user tells you the 6-digit code. Semantica AI — verify the emailed code before asking for a password.

Semantica AI — how to add a site and run the first scan (free) right in this chat: the onboarding steps as in the web app and which tool to call for each. Read it when the user has no project yet or asks what this server can do. No parameters.

Add a publication URL to tracking for a project. The system will monitor AI responses for mentions of this URL.

Remove a publication from tracking for a project.

Publication channel settings of a project: where and under which account the content is published. Secrets (application password, API key) are never returned — only whether the channel is configured.

Get AI-response mentions of tracked publications for a project.

Yandex Wordstat (via Semantica): time series of query volume for a phrase (daily / weekly / monthly). fromDate must be RFC3339 (e.g. 2024-01-01T00:00:00Z). For PERIOD_WEEKLY, use week boundaries (fromDate Sunday, toDate Saturday) per Yandex Search API docs.

Yandex Wordstat (via Semantica): distribution of query volume by region for a phrase over ~30 days. Each row has region (id), count, share, affinityIndex. Map ids to names with yandex_wordstat_regions_tree.

Yandex Wordstat (via Semantica): full hierarchical tree of region ids and labels supported by Wordstat. Large JSON — cache locally; use to resolve region codes from yandex_wordstat_regions.

Yandex Wordstat (via Semantica): popular related search phrases and impression counts for a seed phrase (~30 days). Uses Yandex Search API configured on the Semantica server.

Run an Agent Ready probe for a URL: checks whether major AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, DeepSeek, YandexBot, etc.) can access the page — HTTP status, redirect chain, robots.txt blocks, and captcha/block heuristics. Returns passed, score (0–100), per-bot results, discoverability signals (robots.txt, sitemap hints), and recommendations. Monthly limits: unlimited for paid accounts; 3 checks/month for trial/frozen accounts.

Get the full stored snapshot of a specific Agent Ready check by its history ID (returned by agent_ready_check or agent_ready_history). Includes per-bot results, discoverability signals, recommendations, and request/response diagnostic logs.

List past Agent Ready checks for the authenticated account, optionally filtered by project. Returns check summaries (id, url, passed, score, checkedAt). Use agent_ready_get_check to fetch the full per-bot snapshot of a specific entry.

Get a list of pages/URLs cited in AI responses — for your project domain by default, or for a tracked competitor (competitorId) / arbitrary domain (domain). Optional topicId narrows the report to a single topic (same logic as the in-app topic-scoped competitor view). Results are sorted by citation frequency (highest first).

Catalog of cited sites for the project (second view of the "Mentioned pages" report in the app). Aggregates citation counts and pages per domain, optionally scoped to a tracked competitor / arbitrary domain / topic. Returns { items: [{ domain, count, urls?, promptProviders?, ourPages? }], isCompetitorView? }. Default limit is 100 top domains — increase for larger projects.

Get detailed occurrences of a specific URL being mentioned in AI responses (e.g. "https://competitor.com/page"). url is required — use get_mentioned_pages to discover URLs first, then drill into one. Optional topicId narrows the lookup to a single topic.

Get the full results of a scan by its ID. Renders an interactive results table in MCP Apps hosts (Claude). Includes mention rates, per-provider breakdown, citations, raw AI responses, and noCompanyMention flag per result. Summary totals come from the scan record behind the dashboard, so they match the cabinet. isPartial=true means a top-up scan covering a subset of prompts — its totals describe that subset only. Status values: pending | processing | completed | failed.

Scanning limits of the account: how many prompts per project are still available this week and when the window resets. Check it before a large run — the same limit applies in the dashboard.

Get detailed per-prompt scan results for BI analysis — each row contains a prompt, provider, mention flag, sentiment score, and no_company_mention flag (true = AI response has no company/brand names; false = companies mentioned; null = not yet analyzed). Use onlyNoCompany=true to filter for purely informational responses without brand mentions.

Get all projects belonging to a specific agency client. clientId accepts: UUID, email, domain (e.g. "spiderworks.ae"), or client name (e.g. "John Smith").

Get scans for a specific agency client. clientId accepts: UUID, email, domain, or name.

Generate content for a project with the built-in generators — the "Promotion" section of the dashboard. Required fields depend on type: blog needs projectId + topic; faq needs projectId + topicId + prompts; howto needs projectId + prompt; answer_capsules needs text (a passage to compress into quotable answers). Generation takes minutes and consumes the monthly quota of that generator (see get_content_generation_quota). The result is returned and also stored in history; send a finished piece to the Content Hub with create_content_hub_document_from_generation.

Generate an llm.txt for a site — the map of meanings AI crawlers read to understand what the site is about. Crawls the site, so it takes minutes; the result is stored and can be re-read with get_llm_txt.

Get a high-level summary for all projects: total scans, prompts, last scan date, domain. Use domain to find a project by its domain (partial match, e.g. "os-mena.com").

Get a list of Semantica projects. Semantica staff API keys (admin, team-lead, sales-manager, geo-specialist) automatically return ALL projects across all users — no clientId needed. Pass clientId to list a specific agency client's projects. Use domain to find a project by its domain (partial match, e.g. "os-mena.com").

Publish arbitrary text (not produced by the built-in generators) to a channel — the "custom publication" flow of the dashboard. This publishes for real — confirm with the user first.

Publish a finished generation to a channel. generationId comes from list_content_generations. This publishes for real — confirm with the user first. After publishing, record the URL on the Content Hub document with set_content_hub_published_url so citation tracking starts.

Find user id by email: agency keys resolve among managed clients; Semantica AI staff keys resolve any registered user. Use the id as clientId or pass email directly as clientId / X-Client-Id.

Mark a comment thread as resolved.

Save a new version of a Content Hub document. Only the fields you pass are changed; the previous text is kept as a revision (see get_content_hub_revisions). Saving text counts as an edit and moves the document to "editing".

Configure a publication channel. wordpress: siteUrl + username + applicationPassword (WordPress application password, not the account password), optional default category. tilda: feed title, description, siteUrl, authorName — Tilda pulls the RSS feed. linkedin: apiKey + platformId. Pass only the fields you want to change.

Get a finished structured-data audit by id.

Audit the structured data (JSON-LD schema.org) of a site: what markup exists per page, what is missing, page-level scores and concrete suggestions. Crawls several pages, so it takes minutes.

Why visibility grew or dropped between the last two scans of a project. Same logic as the in-app Insights block "What drove the change in visibility": top prompts, topics and own-domain pages by mention delta, plus mentionRate / totalMentions delta. Returns { available: false, reason } when there is no baseline (one scan) or no aggregate change. Mentions are counted as in summary.totalMentions (hasMention || hasSiteMention || hasZeroClickMention). Pages are limited to project domain + additionalDomains.

Get historical brand visibility rows by provider and scan date — full scans only, matching the dashboard visibility chart (top-up scans of missing prompt/provider pairs are excluded: their totals cover a subset of prompts and would read as false spikes and drops). For a comprehensive report matching the dashboard, use get_project_metrics_report.

Scans that are running right now, with progress (completed vs total prompt × provider pairs). Use it to follow a run started by run_project_scan or rescan_missing_pairs instead of polling results. With waitSeconds the tool waits for the run and streams a terminal-style progress bar meanwhile — always pass a wait when the user asked to watch the scan. It returns before the run is over when the wait runs out (a client that does not read progress notifications would otherwise drop the call): the answer then holds the current panel and asks you to call again — do call again, that repetition is the live view. The answer opens with a monospace panel per running scan: show it to the user verbatim in a code block. An empty list means nothing is running — the scan either finished (read it with get_latest_scan) or was never started.

List agency clients. Agency API key: lists your clients. Semantica staff API key (admin, team-lead, sales-manager, geo-specialist): pass agencyUserId (the agency account uuid); optional filter via resolve by email is a separate tool.

Get ALL projects: your own projects plus all agency clients' projects combined. Semantica AI staff keys must pass agencyUserId so the API knows which agency to aggregate.

Analyze the sentiment of AI responses regarding specific competitors across given scans. Returns sentiment scores per competitor.

Bulk-add topics and/or prompts to an existing project (writes to Semantica topics + prompt_topics). Does not start a scan — schedule or run a scan from the app. Use topics[], promptsByTopic map, and/or flat queries[] (goes to the default topic, stored under the literal title «Основные запросы»). location/siteLanguage apply to NEWLY created topics only — to change geo/language of existing topics use update_project_topics. tags are created on demand and added to the prompts of that block. Limits per call: 100 topics, 500 prompts.

Get a finished blog article by generation id: full text, headings, meta description and images.

History of what was published to a channel for this project: titles, URLs, dates and status.

Competitors Semantica AI suggests tracking for a project — the same card the dashboard shows after a scan: the AI groups the brands and domains that came up in the scan answers next to this brand. Offer it right after the first scan: the user picks who to track, and every later report compares their visibility with those competitors. status: ready — suggestions are in `suggestions`; has_tracked — competitors were already added by hand (read them with get_project_competitors); accepted / dismissed — the card was closed, pass refresh: true to rebuild it; insufficient_data — the scan has too little to go on. The answer opens with a monospace panel: show it to the user verbatim in a code block, the numbers in it are what they answer with. Add the chosen ones with track_competitor_suggestions.

Show how a search model expands one prompt into sub-queries (query fan-out) and which sources it pulls for them. Use it to see what a page must answer to be cited for that prompt. Takes a few minutes.

Semantica AI insights — the "Insights" section of the dashboard: what the scans mean and where the growth is. Returns the current visibility with its change since the previous scan, how many answers name any company at all, the topics where competitors out-mention this brand, the pages of this site the AI models already cite, broken (404) cited pages, ranked action items and content ideas built from competitor and UGC citations. Call it right after the first scan results and the competitor step: it is the closing move of onboarding. The answer opens with a monospace panel — show it to the user verbatim in a code block — and then asks you to write the conclusions yourself, in the user's language, from the JSON below it.

Get the most recent brand visibility scan with an interactive results table (prompts, AI providers, mentions). Same data as get_scan but automatically picks the latest scan — no scan ID required.

Get a previously generated llm.txt by id.

List all tracked publications (articles, pages) for a project.

Scan only the missing prompt × provider pairs of a project, based on the current prompt set and the last completed scans — the "Rescan missing" action in the dashboard. Cheaper than a full run: use it when prompts were added or some providers failed. Runs in the background.

List brand visibility scans with pagination.

Send an approved document to the publication step — the same action as "Send to publication" in the dashboard. From there it goes to the configured channel (WordPress, Tilda, LinkedIn).

Accept the suggested competitors — the "Add" button of the dashboard card: each chosen one goes to the project's tracked competitors with its brand variants and extra domains, and the card stops being offered. Pass competitors to take only some of them (domain or brand name as printed in get_competitor_suggestions), omit it to take all. dismiss: true hides the card without adding anyone — use it when the user says the suggestions are not relevant.

Check that the channel credentials work before publishing (WordPress and LinkedIn). Tilda needs no check — it pulls an RSS feed.

Get the full company writing context for a project — the same aggregated block used in Content Hub validation and AI generation: notes, uploaded files (including site crawl), rules learned from past edits, Telegram chat takes, and extracted file takes. Returns promptBlock (ready to paste into prompts) plus structured sources.

Zero-click positions report: estimated rank of your brand (and tracked competitors) in ordered lists inside AI answers. Same prompts/providers as the dashboard Visibility report. Summary uses the latest full scan; chart uses recent dashboard columns. Optional topicId narrows the report to a single topic. By default the API returns the cached LLM result computed right after a scan; pass forceRefresh=true to re-run the LLM (heavy, 1–3 minutes).