MCP Integration
Finseo provides a Model Context Protocol (MCP) server that lets AI assistants query your visibility data directly.What is MCP?
MCP (Model Context Protocol) is a standard for connecting AI models to external data sources. With Finseo’s MCP server, you can ask Claude, ChatGPT or Cursor natural questions about your AI visibility without writing code. Example: Open Claude and ask:“How has my brand visibility changed in the last 30 days? Which competitors are ahead of me?”Claude automatically queries your Finseo data and provides analysis.
Setup guides
- Claude (claude.ai, Desktop, Code) — OAuth, no API key needed
- ChatGPT (developer mode) — OAuth, no API key needed
- Cursor — API key via headers
Authentication
The MCP server supports two authentication methods:Available tools
All tools are read-only — they retrieve data and never modify it.
The analytics tools accept optional
model (e.g. chatgpt, perplexity, ai_overview, copilot, gemini, grok) and tags filters — the same filters as the dashboard.
get_visibility_metrics, get_visibility_timeseries, get_competitor_ranking and get_sentiment_overview also accept entityLevel and ownEntity (see Entity levels).
Visibility, Mention Rate and Citation Rate
A brand is visible in an AI answer when it is named in the answer text or one of its domains is cited as a source. The tools report all three rates with the same denominator (all analyzed answers), so they can be compared directly (see KPIs explained):visibilityRatePercent— named or cited (the dashboard “Visibility” KPI)mentionRatePercent— named in the answer textcitationRatePercent— own domain (or a configured domain alias) cited as a source
Position vs. mention depth
Tools report two distinct metrics (see KPIs explained):avgMentionOrder— the ordinal Position KPI: average rank among all brands named in an answer (1 = named first, lower is better; e.g.2.3= typically the 2nd–3rd brand mentioned). This matches the#2.3-style Position column on the dashboard competitors page.mentionDepthPercent— Mention Depth: how deep in the answer text the mention appears (0% = very top, lower is better). Not a ranking position.
Timeframes
Every analytics tool defaults to a relative window (timeframeDays, default 30, ending yesterday). For an exact period, pass an absolute range instead:
startDate+endDate(bothYYYY-MM-DD, always together) — overridestimeframeDays.- Supported on
get_visibility_metrics,get_visibility_timeseries(max 90 days),get_competitor_ranking,get_top_sources,get_query_fanouts,get_competitor_gap_analysis,get_competitor_h2handget_sentiment_overview. get_visibility_metricscompares the custom range against the same number of days immediately before it.list_promptsonly supports relative windows.
get_visibility_metrics with startDate: "2026-07-01", endDate: "2026-07-31".
Entity levels
Projects with the entity tree switched on group every mention by entity: companies, sub-brands (brand lines, subsidiaries), products and ingredients.entityLevel picks the level a tool evaluates on:
company(default) — every row is a company; sub-brands, products and ingredients count for their company. “You” is your company.sub_brands— brand lines and subsidiaries as rows of their own, with their products.products— product brands; ingredients count for their product. “You” is your main product (the one with the most answers), or the one you pass asownEntity.ingredients— active substances and materials.
company and once per product on products. Call get_entity_tree first — it returns the levels the project has and ownOptions (the ids you can pass as ownEntity). Projects without a live tree ignore both arguments and report the company grouping.
Example: “How visible is Lorbrena compared to Alecensa?” → get_entity_tree, then get_competitor_ranking with entityLevel: "products", ownEntity: <Lorbrena id>.
Drill-down workflow
Go from overview to detail — the tools chain from broad to a single AI answer:- Competitor track:
get_visibility_metricsfor the big picture →get_competitor_rankingto find the competitors that matter (each row carries anid) →get_competitor_gap_analysis/get_competitor_h2hwith thatcompetitorIdfor the prompt-level “where do we lose and why”. - Prompt track:
list_promptsto find the prompts that matter (each row carries anid) →get_prompt_detailswith thatpromptIdfor the per-answer history and available dates →get_answer_contentwithpromptId+dateto read the exact AI answer, the brands it names and the sources it cites. - Sentiment track:
get_sentiment_overviewfor Share of Voice, the sentiment leaderboard and the most negative statements about any brand. - Tasks track:
list_tasksfor the prioritized optimization backlog (each row carries anid) →get_task_detailswith thattaskIdfor the full action plan and the evidence behind it.
Example prompts
Try asking your AI assistant:- “How visible is my brand in AI search this month, and how did it change vs. the previous period?”
- “How much of my visibility comes from being named vs. being cited as a source? Which prompts are cited-only?”
- “Rank my competitors by AI visibility and run a gap analysis against the strongest one — where do they appear when we don’t?”
- “Which sources do AI models cite most for my tracked prompts, filtered to ChatGPT only?”
- “Compare me head-to-head with competitor X: who gets named first, and what do AI models claim about each of us?”
- “Show me what ChatGPT actually answered yesterday for my prompt ‘best CRM for startups’ — full text and the sources it cited.”
- “What is my Share of Voice, and which negative statements do AI models make about my brand?”
- “What are my most important open optimization tasks, and what exactly should I do for the top one?”
Metric definitions
The tools return the same numbers as the Finseo dashboard and label them explicitly:visibilityRatePercent— share of analyzed AI answers where your brand is visible: named in the answer text OR your own domain cited as a source (the dashboard “Visibility” KPI)mentionRatePercent— share of answers naming your brand in the text (the dashboard “Mention Rate” KPI)citationRatePercent— share of answers citing your own domain or a domain alias as a source (the dashboard “Citation Rate” KPI)promptCoveragePercent— share of tracked prompts with at least one visible answer (a different, usually higher number)brandMentions/ownDomainCitedAnswers— the absolute counts behind Mention Rate and Citation RateownDomainCitations.total— AI answers citing your own domain as a source (the dashboard “Citations” KPI)visibilityIsMentionOnly(competitor ranking) —truewhen the citation leg could not be resolved for that brand andvisibilityRatePercentequals the mention-based rate
Endpoint
initialize, ping, tools/list, and tools/call. Tool results include structuredContent (machine-readable JSON) alongside the text block, per MCP spec 2025-06-18. GET requests to the endpoint return 405 Method Not Allowed — the server does not offer a standalone SSE stream. Unauthenticated requests receive a 401 with OAuth discovery metadata per the MCP authorization spec (RFC 9728).