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:

Method	Best for	How
OAuth 2.1	Claude, ChatGPT	Add the server URL, sign in with your Finseo account — the server supports Dynamic Client Registration and PKCE
API key	Cursor, custom clients	Send `Authorization: Bearer sk_live_...` (create a key)

Available tools

All tools are read-only — they retrieve data and never modify it.

Tool	Description
`list_projects`	List all your projects with `language`, `isPitch` and `models` (the AI models the project’s prompts run on — the valid values for the `model` filter on the other tools)
`get_visibility_metrics`	Visibility KPIs — the dashboard “Visibility” rate (named OR cited), Mention Rate, Citation Rate and the own-domain “Citations” count, with previous-period comparison
`get_visibility_timeseries`	Per-day visibility, mention rate, citation rate, mentions, ordinal position (`avgMentionOrder`), mention depth and sentiment (same values as the dashboard chart)
`list_prompts`	Tracked prompts with metrics (visible, mention rate, citation rate), top competitors and per-prompt citations (paginated via `offset`/`hasMore`) — returns the prompt `id` used by the prompt drill-down tools
`get_prompt_details`	Drill into one prompt: per-model metrics and the full answer history (one row per AI answer with mention, depth, sentiment and brands named)
`get_answer_content`	Read the actual AI answers for one prompt on one day: full answer text, brands with sentiment, and every cited source (`concise`/`detailed` format)
`get_competitor_ranking`	Competitor ranking with the full dashboard KPI set: visibility (named OR cited), mention rate, citation rate, mentions, Share of Voice, ordinal position (`avgMentionOrder`), mention depth, #1/Top-3 share, head-to-head and citations — returns the competitor `id` used by the drill-down tools
`get_competitor_gap_analysis`	Gap analysis vs one competitor: answers where only they appear (your losses), head-to-head, and your wins — with the concrete prompts behind them
`get_competitor_h2h`	Head-to-head vs one competitor: who is named first, average mention order, and LLM-judged comparative claims
`get_sentiment_overview`	Sentiment & Share of Voice: uncapped SoV with explicit denominators, per-brand sentiment leaderboard with win rates and aspect scores, and the most negative LLM-judged statements
`get_top_sources`	Most cited sources with citation counts and source types
`get_tags`	List tags with prompt counts
`get_query_fanouts`	AI query fan-outs (sub-queries) ranked by frequency
`list_tasks`	AI-generated optimization tasks (the dashboard Tasks page) sorted by priority score, with status/category/impact filters — returns the task `id` used by `get_task_details`
`get_task_details`	One task in full: description, step-by-step plan, the evidence that triggered it, and the structured content plan for content tasks

The analytics tools accept optional model (e.g. chatgpt, perplexity, ai_overview, copilot, gemini, grok) and tags filters — the same filters as the dashboard.

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 text
citationRatePercent — own domain (or a configured domain alias) cited as a source

One answer can count in both Mention Rate and Citation Rate, so Visibility ≤ Mention Rate + Citation Rate. Example: “Visibility 50%, Mention Rate 45%, Citation Rate 20%” means 15% of answers name and cite the brand, 30% only name it and 5% only link to it.

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 (both YYYY-MM-DD, always together) — overrides timeframeDays.
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_h2h and get_sentiment_overview.
get_visibility_metrics compares the custom range against the same number of days immediately before it.
list_prompts only supports relative windows.

Example: “Compare my visibility for July 1–31 against the previous month” → the assistant calls get_visibility_metrics with startDate: "2026-07-01", endDate: "2026-07-31".

Drill-down workflow

Go from overview to detail — the tools chain from broad to a single AI answer:

Competitor track: get_visibility_metrics for the big picture → get_competitor_ranking to find the competitors that matter (each row carries an id) → get_competitor_gap_analysis / get_competitor_h2h with that competitorId for the prompt-level “where do we lose and why”.
Prompt track: list_prompts to find the prompts that matter (each row carries an id) → get_prompt_details with that promptId for the per-answer history and available dates → get_answer_content with promptId + date to read the exact AI answer, the brands it names and the sources it cites.
Sentiment track: get_sentiment_overview for Share of Voice, the sentiment leaderboard and the most negative statements about any brand.
Tasks track: list_tasks for the prioritized optimization backlog (each row carries an id) → get_task_details with that taskId for 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 Rate
ownDomainCitations.total — AI answers citing your own domain as a source (the dashboard “Citations” KPI)
visibilityIsMentionOnly (competitor ranking) — true when the citation leg could not be resolved for that brand and visibilityRatePercent equals the mention-based rate

Endpoint

POST https://api.finseo.ai/v1/mcp

The server implements JSON-RPC 2.0 over Streamable HTTP (stateless) and supports 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).

​MCP Integration

​What is MCP?

​Setup guides

​Authentication

​Available tools

​Visibility, Mention Rate and Citation Rate

​Position vs. mention depth

​Timeframes

​Drill-down workflow

​Example prompts

​Metric definitions

​Endpoint