MentionFlow AI
Open app
DocsAPI & MCP

MCP server

A Model Context Protocol endpoint that exposes MentionFlow's reads as tools an AI agent can call — the setup, the protocol details, and all eleven tools.

The MCP server exposes the same reads as the REST API as tools an AI agent can call over the Model Context Protocol. It is stateless, read-only, and backed by the identical computations — so an MCP answer and a dashboard number never disagree.

Endpoint and setup

  • Endpoint: POST https://mentionflow.ai/api/mcp (Streamable HTTP). A GET returns 405 with Allow: POST.
  • Auth: the same bearer key as REST (Authorization: Bearer mf_…); an ingest-scoped key is rejected with 403. See Authentication.

Configure an MCP client with an HTTP transport:

{
  "type": "http",
  "url": "https://mentionflow.ai/api/mcp",
  "headers": { "Authorization": "Bearer mf_your_key_here" }
}

Protocol

  • JSON-RPC 2.0. Supported methods: initialize, ping, tools/list, tools/call.
  • Protocol versions offered: 2025-06-18, 2025-03-26, 2024-11-05 (the server echoes your requested version if supported, else the newest).
  • Server identity: { "name": "mentionflow", "version": "1.0.0" }, advertising a tools capability.
  • Batches may contain at most 10 messages (see Limits).

Every tool returns a single text content block whose text is the JSON payload — the same shape as the matching REST resource. A tool that runs but fails (e.g. an unknown brand) returns a normal result flagged isError: true rather than a protocol error; check that flag. See Errors.

The brand argument

Every tool except list_brands accepts one optional argument:

{ "brand_id": "<id from list_brands; defaults to your first brand>" }

brand_id is optional. Omit it to use your first brand; an out-of-scope or unknown id returns {"error":"Unknown brand id: <id>"}.

Tools

All payload shapes and scales match the Resource reference and Conventions.

ToolArgumentReturnsCap
list_brandsnoneyour brands (id, name, domain)—
get_overviewbrand_id?the visibility scorecard—
list_promptsbrand_id?tracked prompts with per-prompt presence, visibility, average positionall active
list_competitorsbrand_id?the competitor leaderboard (your brand row included)all entities
list_sourcesbrand_id?cited domains with counts and classification20
list_urlsbrand_id?URL-level citation rows — the individual cited pages behind list_sources; see /api/v1/urls50
list_answersbrand_id?recent runs: engine, model, region, ordered mentions, citations50
list_shopping_productsbrand_id?the shopping product leaderboard30
get_shopping_trendbrand_id?the daily shopping-carousel time series7-day
get_metrics_historymetric (required), brand_id?, days?/from?+to?, engine?, competitors?daily metric time series (visibility, share-of-voice fraction, citation share, sentiment) — see /api/v1/metrics/history366 days
get_crawler_analyticsbrand_id?, days? (7/14/28)AI-agent activity on the brand's own site + robots.txt verdicts, honest-null rules embedded in the description — see /api/v1/crawlers; Growth+ plans, the same gate as the /crawlers pageall known agents
Note

list_answers returns 50 rows over MCP; the REST /api/v1/answers returns 200. Everything else matches its REST counterpart.

The shopping tools' descriptions embed the honesty contract directly, so an agent reading them gets the rules in context — for example, list_shopping_products states that totals.carousels = 0 with an empty product list "means no carousels were captured this window — report that as absence of data, never as shopping presence", and get_shopping_trend states that own_avg_position is "null on days the brand was not on the shelf — null is not zero" and that fewer than two observed days is "a snapshot, not a trend". The list_shopping_products description also documents the channel_coverage block: status parses-today "means the engine's payloads carry parseable product data", awaiting-payload "means extraction is wired but the data vendor delivers no product fields yet", and carousels "is null when unobservable (engine not sampled, or vendor payload missing) — null is NOT zero".

Related