MencionAI MCP

Use the MencionAI MCP server to read AI search visibility, enqueue scans, and brief GEO / social / blog drafts from Cursor, Claude, ChatGPT, Codex, Antigravity, n8n, or any MCP client.

The MCP server is a thin adapter over Public API v2. It uses your API key and the same scopes as the HTTP API. Tools never talk to the database directly.

Easy URLs for agents (they redirect to this site):

Canonical pages stay on www.mencionai.com/{locale}/docs/....

Clients

Client	Doc	`get_doc` id
Cursor	Cursor	`mcp-cursor`
Claude Desktop / Claude Code	Claude	`mcp-claude`
ChatGPT	ChatGPT	`mcp-chatgpt`
Codex	Codex	`mcp-codex`
Antigravity	Antigravity	`mcp-antigravity`
n8n	n8n	`mcp-n8n`
VS Code / Copilot	note below	(hub only)

Settings → API Keys also has copy-paste snippets.

Before you begin

Create an API key under Settings → API Keys (mak_live_… or mak_test_…).
Install Node.js 20+ (for local stdio). n8n does not need this. It talks to hosted MCP over HTTP.
Grant scopes that match what you need:
- organization:read + workspaces:read — list workspaces and read visibility
- jobs:read + workspaces:write — enqueue / wait for scans
- visibility:answers:read — answer excerpts (included on Settings keys)

Never pass the API key as a tool argument. Put it in the MCP process environment (stdio) or as Authorization: Bearer (hosted).

Local stdio

pnpm add -g @mencionai/mcp
# or: npx -y @mencionai/mcp

Hosted MCP (preferred for production agents)

URL: https://mcp.mencionai.com/mcp

Authenticate with Authorization: Bearer YOUR_API_KEY. Stdio from customer machines does not write product telemetry.

OAuth connector (no API key)

Clients that speak OAuth 2.1 can connect without pasting a key. Point the client at https://mcp.mencionai.com/mcp and let it discover the rest. In Claude Desktop, use Settings → Connectors and paste that URL. In ChatGPT, install from the Plugins tab and leave registration on dynamic registration. See ChatGPT.

Manage grants under Settings → Connected apps.

Preferred tool flow

For how-to / setup questions, call list_docs then get_doc (api, sdk, whitelabel, ars, mcp, mcp-cursor, mcp-claude, mcp-chatgpt, mcp-codex, mcp-antigravity, mcp-n8n, llms) before inventing answers. Docs tools do not need an API key.

For visibility data:

list_workspaces
get_visibility_overview
explain_visibility_gaps / compare_competitors
Prompts: list_prompts → analyze_prompt. add_prompt tracks a question. update_prompt edits the wording or sets is_active.
“What should we do?”: analyze_action_plan then analyze_sources. Writes: add_action_plan_step, edit_action_plan_step, or complete_action_plan_step with a required description.
Weekly briefing: analyze_weekly_report · AI recommendation score: analyze_ai_recommendation_score
GEO / social / blog drafts: research_geo_practices (you must web-search) then prepare_geo_content_brief. After writing a blog draft, call validate_geo_content.
Site diagnostic: analyze_site (workspace domain only, bounded), then identify_site_stack and list_site_pages. Public homepage checks for any domain: call one site_check_* tool with that domain.
If crawl insights are empty, get_crawl_insights then ask the user for CSV or a Vercel Log Drain before inventing traffic; ingest with ingest_crawl_insights_csv
wait_for_ai_search_scan when a refresh is needed (uses plan quota)

Do not call thin tools (visibility_summary, visibility_mentions, visibility_competitors, visibility_coverage, visibility_citations, get_weekly_report, get_action_plan, get_ai_sources) unless composed output is insufficient. visibility_responses requires visibility:answers:read.

Tools

Tool	Purpose
`list_docs` / `get_doc`	Public guides (API, SDK, whitelabel, ARS, MCP, client setup, llms.txt)
`get_visibility_overview`	Start here — composed snapshot
`compare_competitors`	Rank rivals vs brand
`explain_visibility_gaps`	Prompts where competitors appear but the brand does not
`wait_for_ai_search_scan`	Start an AI search mention scan and wait (consumes quota)
`visibility_series`	Daily scores including ARS
`get_traffic_summary` / `get_traffic_series`	AI referral visits from the site snippet
`get_organization` / `list_workspaces` / `get_workspace`	Org (includes `covered_providers`) and workspace reads
`visibility_responses`	Answer excerpts (`visibility:answers:read`)
`list_prompts` / `get_prompt` / `analyze_prompt` / `add_prompt` / `update_prompt`	Tracked questions. `add_prompt` creates one. `update_prompt` edits text or sets active.
`submit_feedback`	Send a product note to MencionAI. Optional `anonymous`. Does not list notes.
`analyze_weekly_report` / `get_weekly_report`	Weekly visibility briefing
`analyze_action_plan` / `get_action_plan` / `add_action_plan_step` / `edit_action_plan_step` / `complete_action_plan_step`	This month’s GEO checklist (writes need a description)
`analyze_ai_recommendation_score` / `get_ai_recommendation_score`	AI recommendation score and its eight components
`analyze_sources` / `get_ai_sources`	Cited domains and citation gaps
`get_brand_perception`	Brand vs competitor attributes
`analyze_site`	Bounded live audit of the workspace domain
`identify_site_stack`	Detect CMS, host, and framework for the workspace domain
`list_site_pages`	Every sitemap URL (blog, content, product), including a 100-page blog
`site_check_ai_crawler_robots`	Fetch a public site and check whether robots.txt allows the tracked AI crawlers
`site_check_homepage_visible_text`	Fetch a public homepage and check that the main text is in the HTML
`site_check_homepage_not_noindex`	Fetch a public homepage and check that it is not noindex
`site_check_sitemap_urls`	Fetch a public sitemap and check that its URLs resolve
`site_check_sitemap_freshness`	Fetch a public sitemap and check that its dates are recent
`site_check_canonical_and_hreflang`	Fetch a public homepage and check canonical and hreflang
`site_check_title_and_description`	Fetch a public homepage and check the title and meta description
`site_check_single_h1`	Fetch a public homepage and check that it has one H1
`site_check_open_graph_tags`	Fetch a public homepage and check Open Graph tags
`site_check_robots_tag_agreement`	Fetch a public homepage and check that robots tags agree
`site_check_llms_txt`	Fetch a public site and check llms.txt
`site_check_ai_txt_and_llms_full`	Fetch a public site and check ai.txt and llms-full.txt
`site_check_llms_txt_links`	Fetch a public llms.txt and check that its links resolve
`site_check_citation_signals`	Fetch a public homepage and check citation signals
`site_check_json_ld`	Fetch a public homepage and check JSON-LD
`site_check_question_headings`	Fetch a public homepage and check question-style headings
`get_crawl_insights` / `ingest_crawl_insights_csv`	Crawler aggregates; ask the user for CSV or Vercel Log Drain when empty
`get_project_settings`	Brand name, domain, competitors, business type, location
`research_geo_practices`	Host-LLM research task (must web-search)
`prepare_geo_content_brief`	Writing brief for blog / LinkedIn / Instagram / X / Facebook
`validate_geo_content`	Check a customer blog draft against the GEO/AEO/SEO/AIO citation contract
`start_content_job`	Start one draft job for a content Plan of Action step. Returns the job id and state. Does not publish.
`connect_blog_domain`	CNAME for `blog.{domain}`. The customer adds it at their domain host. Does not change the store address.
`connect_traffic_snippet`	Public tracking script for the website `<head>`. Creates a key only when `create` is true.
`create_post_with_agent`	Start the content agent for a content Plan of Action step. Spends 2 credits and fills the next open daily time.
`get_blog_health`	Customer blog checks: domain, SSL, publish, access, posts, keywords, SEO, GEO, AIO, AEO, schema, theme, robots.txt, sitemap.xml, llms.txt.
`get_blog_settings`	Style, font, uploaded font, colors, logo, author, social links, pixels, three CTAs, footer switch, categories, tags, daily times, and publish policy.
`update_blog_settings`	Change any of those settings. A listed font clears an uploaded file unless `font_file_url` is sent too. Does not publish.
`set_blog_appearance`	Change the template (magazine, editorial, index, gallery), theme (ink, paper, signal, aurora), and font. Does not publish. A workspace that mirrors onto the MencionAI blog applies the same template, colors, and font there. The site background stays.
`import_blog_content`	Import a WordPress, Blogger, or RSS file as draft posts. The same source is skipped on a later import. Does not publish and does not spend credits.
`export_blog_content`	Download the workspace posts as WordPress, Blogger, or RSS. The file matches the importer.
`upload_blog_font`	Upload a woff2, woff, ttf, or otf file (max 2MB) and use it on the blog.
`upload_blog_logo`	Upload a png, jpeg, or webp logo (max 5MB).
`get_content_calendar`	Scheduled and published posts with day, time, state, and status.
`get_content_job`	One content job: state, subject, slug, schedule, sections, sources, links, and each section’s call to action and image.
`update_content_post`	Edit a post by section: body, sources, call to action, and image. Each section keeps its own call to action and image. Does not publish.
`reschedule_content_job`	Move an unpublished draft to another day and time. A past day or a taken slot is rejected.
`retry_content_job`	Rewind a failed or blocked job and run it again. Does not debit credits again.
`get_blog_telemetry`	Published post traffic: impressions, direct, SEO, AI, CTA clicks, total, CTR, and which AI products visited.
`visibility_coverage` / `visibility_citations` / `visibility_summary` / `visibility_mentions` / `visibility_competitors`	Power-user thin reads
`enqueue_visibility_scan` / `get_job`	Manual scan + poll
`start_onboarding_v2_scan` / `wait_for_onboarding_v2_report` / `get_onboarding_v2_report`	Start, wait for, and read the onboarding AI search scan

GEO content briefs

research_geo_practices returns per-model live-search queries and official docs for every engine MencionAI can track (ChatGPT, Gemini, Google AI Studio, Claude, Grok, DeepSeek, Perplexity). Customer-facing drafts should still name only plan-covered models. The host LLM must search the live web, fetch must_fetch_urls, and review the workspace domain plus discovered social profiles. Then prepare_geo_content_brief assembles visibility gaps, open GEO steps, and the same citation contract used to publish first-party MencionAI pages (Sources, FAQ, Related reading on the brand domain). After writing, validate_geo_content returns missing_obligations and fails closed. Default market is Brazil (pt-br / br). Never invent crawler tokens for Grok or DeepSeek.

VS Code / Copilot

.vscode/mcp.json uses servers (not mcpServers) and "type": "stdio". Do not paste the Cursor JSON unchanged.

Troubleshooting

Symptom	What to check
401 / unauthorized	API key missing, revoked, or wrong environment (`mak_live_` vs `mak_test_`)
Scope / forbidden errors	Key lacks `workspaces:read` (or scan write scopes)
`visibility_responses` returns MISSING_SCOPE	Create a new Settings key or add `visibility:answers:read`
Scan slow or rejected	Plan quota; prefer `wait_for_ai_search_scan` with a timeout ≤ 120s
Agent asks for your API key	Misconfigured MCP — key belongs in env / Bearer header, never in tool args

Next steps

Cursor

File: .cursor/mcp.json (or Cursor MCP settings).

Stdio

{
  "mcpServers": {
    "mencionai": {
      "command": "npx",
      "args": ["-y", "@mencionai/mcp"],
      "env": {
        "MENCIONAI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Hosted

{
  "mcpServers": {
    "mencionai": {
      "url": "https://mcp.mencionai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Vanity URL: docs.mencionai.com/mcp. Back to the MCP hub.

Claude

Claude Desktop

Open Settings → Connectors, add a custom connector, and paste:

https://mcp.mencionai.com/mcp

Claude runs OAuth 2.1 automatically. You do not need an API key or claude_desktop_config.json.

Manage grants in MencionAI under Settings → Connected apps.

Claude Code

Project .mcp.json, or:

claude mcp add mencionai -- npx -y @mencionai/mcp

Set MENCIONAI_API_KEY in the MCP server environment. Hosted:

{
  "mcpServers": {
    "mencionai": {
      "url": "https://mcp.mencionai.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Vanity URL: docs.mencionai.com/mcp. Back to the MCP hub.

ChatGPT

Install MencionAI from the Plugins tab. Leave registration on dynamic registration.

Plugins tab

Open Plugins.
Search for MencionAI and install it.
When a tool runs, sign in at www.mencionai.com and allow the app.
Leave registration on dynamic registration.

Until the public listing is available, install this repository's marketplace. The catalog is .agents/plugins/marketplace.json and the package is plugins/mencionai. Restart the ChatGPT desktop app, open Plugins, choose that marketplace, and install MencionAI.

Developer mode fallback

Use this when the listing is not in the directory yet.

Open Settings → Security and login and turn on Developer mode.
Open Plugins, choose +, and add this server URL:

https://mcp.mencionai.com/mcp

The first time a tool runs, sign in at www.mencionai.com and allow the app.
Leave registration on dynamic registration.

Manage grants in MencionAI under Settings → Connected apps.

Vanity URL: docs.mencionai.com/mcp/chatgpt. Back to the MCP hub.

Codex

File: ~/.codex/config.toml (or project .codex/config.toml on a trusted repo).

The table name is mcp_servers, not mcpServers.

Stdio

[mcp_servers.mencionai]
command = "npx"
args = ["-y", "@mencionai/mcp"]

[mcp_servers.mencionai.env]
MENCIONAI_API_KEY = "YOUR_API_KEY"

Hosted

[mcp_servers.mencionai]
url = "https://mcp.mencionai.com/mcp"
bearer_token_env_var = "MENCIONAI_API_KEY"

Verify with codex mcp list or /mcp in the TUI.

Vanity URL: docs.mencionai.com/mcp. Back to the MCP hub.

Antigravity

Global file: ~/.gemini/config/mcp_config.json. Workspace file: .agents/mcp_config.json.

Stdio

{
  "mcpServers": {
    "mencionai": {
      "command": "npx",
      "args": ["-y", "@mencionai/mcp"],
      "env": {
        "MENCIONAI_API_KEY": "${MENCIONAI_API_KEY}"
      }
    }
  }
}

Hosted

Antigravity remote servers use serverUrl, not url.

{
  "mcpServers": {
    "mencionai": {
      "serverUrl": "https://mcp.mencionai.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MENCIONAI_API_KEY}"
      }
    }
  }
}

Gemini CLI leftover

Older Gemini CLI still reads mcpServers inside ~/.gemini/settings.json. Prefer the Antigravity mcp_config.json path above.

Vanity URL: docs.mencionai.com/mcp. Back to the MCP hub.

n8n

n8n is an HTTP MCP client. It does not spawn npx @mencionai/mcp. Do not use n8n’s MCP Server Trigger for MencionAI. That node exposes n8n as a server.

Use MCP Client Tool on an AI Agent, or the standalone MCP Client node.

Node fields (v1.2+)

Field	Value
Server Transport	HTTP Streamable (`httpStreamable`)
MCP Endpoint URL / Endpoint	`https://mcp.mencionai.com/mcp`
Authentication	Bearer Auth
Token	Settings API key (`mak_live_…` or `mak_test_…`)

Older node versions default to SSE. Hosted MencionAI MCP is Streamable HTTP. Pick HTTP Streamable.

Self-hosted n8n only needs outbound HTTPS to mcp.mencionai.com. Optional: MCP OAuth2 against the same URL (discovery via WWW-Authenticate).

Vanity URL: docs.mencionai.com/mcp. Back to the MCP hub.