MencionAI MCP

Use o servidor MCP da MencionAI para ler visibilidade em buscas de IA, enfileirar scans e briefar rascunhos GEO / social / blog no Cursor, Claude, ChatGPT, Codex, Antigravity, n8n ou qualquer cliente MCP.

O servidor MCP é um adaptador fino sobre a API pública v2. Usa a sua chave de API e os mesmos scopes da API HTTP. As tools nunca falam com o banco diretamente.

URLs fáceis para agentes (redirecionam para este site):

As páginas canônicas ficam em www.mencionai.com/{locale}/docs/....

MCP para agências

Funcionalidade planejada. O MCP para agências ainda não está implementado. O endpoint proposto é https://mcp.mencionai.com/agency/mcp. Isso não é uma instrução de conexão funcional. Ainda não foram publicados nomes de ferramentas, escopos ou exemplos de configuração para agências.

A proposta da plataforma de agências oferece uma conexão autorizada para os clientes permitidos da agência. O endpoint atual de cliente, https://mcp.mencionai.com/mcp, continua limitado a uma organização. Informar outro workspace não permite que a credencial acesse a organização de outro cliente.

Conexão e permissões planejadas

O MCP para agências usa um consentimento OAuth separado para a agência, os clientes permitidos e as permissões de leitura ou escrita. Cada operação seleciona explicitamente a organização do cliente e o workspace. O servidor verifica o vínculo atual do usuário, a relação entre agência e cliente, o acesso ao workspace, a permissão da operação e os limites do plano do cliente.

Remover a relação com a agência ou o vínculo do usuário deve bloquear as próximas operações, inclusive em uma conexão MCP já aberta. As credenciais de agência são separadas das credenciais de cliente e de administrador da plataforma. Um domínio white-label do portal não concede acesso ao MCP nem altera seu endpoint canônico.

Os exemplos de configuração abaixo são do MCP de cliente existente, não do serviço planejado para agências. Não substitua a URL pelo endpoint proposto antes da disponibilização da autenticação e das ferramentas de agência.

Operações planejadas

Área	Cobertura pretendida
Clientes e acesso	Listar e criar clientes autorizados, selecionar workspaces e gerenciar convites permitidos.
Planos e cobrança	Ler o plano e a situação de cobrança de cada cliente, solicitar capacidade a vendas e iniciar somente ações de cobrança aprovadas explicitamente.
Visibilidade	Reutilizar ferramentas de cliente para prompts, scans, concorrentes, fontes, planos de ação, relatórios, auditorias de site e tráfego.
Blogs e conteúdo	Criar e configurar blogs dos clientes, importar ou exportar conteúdo, consultar o calendário, editar rascunhos e acompanhar tarefas de conteúdo.
MAIagent	Iniciar fluxos de agente disponíveis para o cliente selecionado, acompanhar tarefas assíncronas e preservar as verificações de créditos e cotas daquele cliente.
White-label	Consultar e gerenciar operações permitidas de cadastro e verificação de domínios do portal quando essas APIs estiverem disponíveis.

Esta é a cobertura pretendida, não um catálogo executável. O catálogo publicado deve identificar as operações implementadas e as exclusões. O MCP de agência reutiliza os serviços de cliente. Ele não conecta recursivamente os MCPs dos clientes nem usa representação de administrador da plataforma.

Fluxo esperado e proteções

O fluxo planejado descobre os clientes permitidos, seleciona um cliente e um workspace, executa a operação autorizada e acompanha o identificador de tarefa retornado. Criar um rascunho de blog ou uma tarefa MAIagent não equivale a publicar um post.

Scans e operações de agente usam os créditos e as cotas do cliente selecionado, nunca o saldo de outro cliente ou a conta Starter gratuita da agência. Chamadas que gastam créditos devem informar o custo. Publicações, alterações de cobrança, remoção de membros e operações destrutivas exigem aprovação explícita. A repetição de um resultado incerto deve preservar a chave de idempotência original.

Até a disponibilização, os IDs existentes mcp e whitelabel de get_doc contêm estas seções planejadas. Ainda não existem os IDs de documentação agencies ou mcp-agency.

Clientes

Cliente	Doc	id `get_doc`
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	nota abaixo	(apenas hub)

Settings → API Keys também tem snippets para copiar.

Antes de começar

Crie uma chave em Settings → API Keys (mak_live_… ou mak_test_…).
Instale Node.js 20+ (stdio local). n8n não precisa disso: fala com o MCP hospedado via HTTP.
Conceda os scopes necessários:
- organization:read + workspaces:read — listar workspaces e ler visibilidade
- jobs:read + workspaces:write — enfileirar / esperar scans
- visibility:answers:read — trechos de resposta (incluso nas chaves do Settings)

Nunca passe a chave como argumento de tool. Coloque no ambiente do processo MCP (stdio) ou em Authorization: Bearer (hospedado).

Stdio local

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

MCP hospedado (preferido para agentes em produção)

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

Autentique com Authorization: Bearer YOUR_API_KEY. Stdio em máquinas do cliente não envia telemetria de produto.

Conector OAuth (sem chave de API)

Clientes OAuth 2.1 podem conectar sem colar a chave. Aponte para https://mcp.mencionai.com/mcp. No Claude Desktop, use Settings → Connectors e cole essa URL. No ChatGPT, instale pela aba Plugins e deixe o registro em registro dinâmico. Veja ChatGPT.

Gerencie grants em Settings → Connected apps.

Fluxo preferido das tools

Para dúvidas de setup, chame list_docs e depois get_doc (api, sdk, whitelabel, ars, mcp, mcp-cursor, mcp-claude, mcp-chatgpt, mcp-codex, mcp-antigravity, mcp-n8n, llms) antes de inventar respostas. Tools de docs não precisam de chave.

Para dados de visibilidade:

list_workspaces
get_visibility_overview
explain_visibility_gaps / compare_competitors
Prompts: list_prompts → analyze_prompt. add_prompt acompanha uma pergunta. update_prompt edita o texto ou define is_active.
“O que fazer?”: analyze_action_plan depois analyze_sources
Briefing semanal: analyze_weekly_report · pontuação de recomendação de IA: analyze_ai_recommendation_score
Rascunhos GEO / social / blog: research_geo_practices (você deve buscar na web) depois prepare_geo_content_brief. Depois de escrever um rascunho de blog, chame validate_geo_content.
wait_for_ai_search_scan quando precisar atualizar (usa cota do plano)

Não chame tools finas (visibility_summary, visibility_mentions, visibility_competitors, visibility_coverage, visibility_citations, get_weekly_report, get_action_plan, get_ai_sources) a menos que a saída composta seja insuficiente. visibility_responses exige visibility:answers:read.

Tools

Tool	Propósito
`list_docs` / `get_doc`	Guias públicos (API, SDK, whitelabel, ARS, MCP, setup de clientes, llms.txt)
`get_visibility_overview`	Comece aqui — snapshot composto
`compare_competitors`	Ranking de rivais vs marca
`explain_visibility_gaps`	Prompts em que concorrentes aparecem e a marca não
`wait_for_ai_search_scan`	Inicia um scan de busca em IA e espera (consome cota)
`visibility_series`	Scores diários incluindo ARS
`get_traffic_summary` / `get_traffic_series`	Visitas de indicação de IA do snippet
`get_organization` / `list_workspaces` / `get_workspace`	Org (inclui `covered_providers`) e workspaces
`visibility_responses`	Trechos de resposta (`visibility:answers:read`)
`list_prompts` / `get_prompt` / `analyze_prompt` / `add_prompt` / `update_prompt`	Perguntas rastreadas. `add_prompt` cria. `update_prompt` edita o texto ou ativa.
`submit_feedback`	Envia uma nota de produto à MencionAI. `anonymous` opcional. Não lista notas.
`analyze_weekly_report` / `get_weekly_report`	Briefing semanal
`analyze_action_plan` / `get_action_plan` / `edit_action_plan_step` / `complete_action_plan_step`	Ações da MAI a partir do diagnóstico do site (escritas exigem descrição; passos novos vêm só do chat MAI)
`analyze_ai_recommendation_score` / `get_ai_recommendation_score`	Pontuação de recomendação de IA e seus oito componentes
`analyze_sources` / `get_ai_sources`	Domínios citados e gaps
`get_brand_perception`	Atributos da marca vs concorrentes
`analyze_site`	Auditoria limitada do domínio do workspace
`identify_site_stack`	Detecta CMS, host e framework do domínio
`list_site_pages`	Todas as URLs do sitemap (blog, conteúdo, produto), inclusive um blog de 100 páginas
`list_content_hosts`	Apex, www, blog, blog da plataforma, hosts ligados na homepage e labels docs/content/help com sitemap
`site_check_llms_txt` / `site_check_ai_crawler_robots` / outras tools `site_check_*`	Uma checagem pública da homepage em qualquer domínio. Não exige workspace
`get_crawl_insights` / `ingest_crawl_insights_csv`	Agregados de crawler; peça CSV ou Vercel Log Drain se vazio
`get_project_settings`	Nome da marca, domínio, concorrentes, tipo de negócio, localização
`research_geo_practices`	Tarefa de pesquisa para o LLM host (precisa buscar na web)
`prepare_geo_content_brief`	Brief de escrita para blog / LinkedIn / Instagram / X / Facebook
`validate_geo_content`	Valida um rascunho de blog do cliente contra o contrato de citação GEO/AEO/SEO/AIO
`start_content_job`	Inicia um job de rascunho para um passo de conteúdo do Plano de Ação. Devolve o id e o estado. Não publica.
`connect_blog_domain`	CNAME de `blog.{domain}`. O cliente adiciona no provedor do domínio. O endereço da loja permanece o mesmo.
`connect_traffic_snippet`	Script público de rastreamento para o `<head>` do site. Cria uma chave só quando `create` é true.
`create_post_with_agent`	Inicia o agente de conteúdo para um passo de conteúdo do Plano de Ação. Gasta 2 créditos e ocupa o próximo horário diário livre.
`get_blog_health`	Verificações do blog: domínio, SSL, publicação, acesso, posts, palavras-chave, SEO, GEO, AIO, AEO, schema, tema, robots.txt, sitemap.xml e llms.txt.
`get_blog_settings`	Estilo, fonte, fonte enviada, cores, logo, autor, redes, pixels, três CTAs, rodapé, categorias, tags, horários e política de publicação.
`update_blog_settings`	Altera qualquer um desses campos. Uma fonte da lista remove o arquivo enviado, salvo se `font_file_url` vier na mesma chamada. Não publica.
`set_blog_appearance`	Muda o modelo (magazine, editorial, index, gallery), o tema (ink, paper, signal, aurora) e a fonte. Não publica. Um workspace que espelha o blog da MencionAI aplica o mesmo modelo, as mesmas cores e a mesma fonte lá. O fundo do site permanece.
`import_blog_content`	Importa um arquivo WordPress, Blogger ou RSS como rascunhos. A mesma origem é ignorada numa importação seguinte. Não publica e não gasta créditos.
`export_blog_content`	Baixa os posts do workspace em WordPress, Blogger ou RSS. O arquivo é o mesmo que o importador lê.
`upload_blog_font`	Envia um arquivo woff2, woff, ttf ou otf (máx. 2MB) e usa no blog.
`upload_blog_logo`	Envia um logo png, jpeg ou webp (máx. 5MB).
`get_content_calendar`	Posts agendados e publicados, com dia, hora, estado e status.
`get_content_job`	Um job: estado, assunto, slug, agenda, seções, fontes, links, chamadas e a imagem.
`update_content_post`	Edita um post por seção: texto, fontes, chamada e imagem. Uma imagem por artigo. Não publica.
`reschedule_content_job`	Move um rascunho não publicado para outro dia e hora. Dia passado ou horário ocupado é recusado.
`retry_content_job`	Recomeça um job com falha ou bloqueado. Não debita créditos de novo.
`get_blog_telemetry`	Tráfego dos posts publicados: impressões, direto, SEO, IA, cliques no CTA, total, CTR e quais IAs visitaram.
`visibility_coverage` / `visibility_citations` / `visibility_summary` / `visibility_mentions` / `visibility_competitors`	Leituras finas
`enqueue_visibility_scan` / `get_job`	Scan manual + poll
`start_onboarding_v2_scan` / `wait_for_onboarding_v2_report` / `get_onboarding_v2_report`	Inicia, espera e lê o scan de busca em IA do onboarding

Briefs de conteúdo GEO

research_geo_practices devolve queries de busca ao vivo e docs oficiais por modelo para cada engine que a MencionAI monitora (ChatGPT, Gemini, Google AI Studio, Claude, Grok, DeepSeek, Perplexity). Rascunhos para o cliente ainda devem nomear só os modelos do plano. O LLM host deve buscar na web, baixar must_fetch_urls e revisar o domínio do workspace e perfis sociais descobertos. Depois prepare_geo_content_brief monta gaps de visibilidade, passos GEO abertos e o mesmo contrato de citação usado nas páginas first-party da MencionAI (Fontes, FAQ, Leitura relacionada no domínio da marca). Depois de escrever, validate_geo_content devolve missing_obligations e falha fechado. Mercado padrão: Brasil (pt-br / br). Nunca invente tokens de crawler para Grok ou DeepSeek.

VS Code / Copilot

.vscode/mcp.json usa servers (não mcpServers) e "type": "stdio". Não cole o JSON do Cursor sem adaptar.

Troubleshooting

Sintoma	O que checar
401 / unauthorized	Chave ausente, revogada ou ambiente errado (`mak_live_` vs `mak_test_`)
Scope / forbidden	Falta `workspaces:read` (ou scopes de escrita de scan)
`visibility_responses` retorna MISSING_SCOPE	Crie uma chave nova no Settings ou adicione `visibility:answers:read`
Scan lento ou recusado	Cota do plano; prefira `wait_for_ai_search_scan` com timeout ≤ 120s
Agente pede a chave	MCP mal configurado — a chave fica em env / Bearer, nunca em args de tool

Próximos passos

Cursor

Arquivo: .cursor/mcp.json (ou as configurações MCP do Cursor).

Stdio

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

Hospedado

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

URL curta: docs.mencionai.com/mcp. Voltar ao hub MCP.

Claude

Claude Desktop

Abra Settings → Connectors, adicione um conector personalizado e cole:

https://mcp.mencionai.com/mcp

O Claude faz o OAuth 2.1 automaticamente. Não é preciso chave de API nem editar claude_desktop_config.json.

Gerencie grants no MencionAI em Settings → Connected apps.

Claude Code

.mcp.json do projeto, ou:

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

Defina MENCIONAI_API_KEY no ambiente do servidor MCP. Hospedado:

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

URL curta: docs.mencionai.com/mcp. Voltar ao hub MCP.

ChatGPT

Instale a MencionAI na aba Plugins. Deixe o registro em registro dinâmico.

Aba Plugins

Abra Plugins.
Busque MencionAI e instale.
Quando uma tool rodar, entre em www.mencionai.com e autorize o app.
Deixe o registro em registro dinâmico.

Enquanto a listagem pública não estiver disponível, instale o marketplace deste repositório. O catálogo é .agents/plugins/marketplace.json e o pacote é plugins/mencionai. Reinicie o app desktop do ChatGPT, abra Plugins, escolha esse marketplace e instale a MencionAI.

Fallback no modo desenvolvedor

Use isto quando a listagem ainda não estiver no diretório.

Abra Settings → Security and login e ligue Developer mode.
Abra Plugins, escolha + e cole esta URL:

https://mcp.mencionai.com/mcp

Na primeira tool, entre em www.mencionai.com e autorize o app.
Deixe o registro em registro dinâmico.

Gerencie grants em Settings → Connected apps.

URL curta: docs.mencionai.com/mcp/chatgpt. Voltar ao hub MCP.

Codex

Arquivo: ~/.codex/config.toml (ou .codex/config.toml do projeto em um repo confiável).

O nome da tabela é mcp_servers, não mcpServers.

Stdio

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

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

Hospedado

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

Confira com codex mcp list ou /mcp no TUI.

URL curta: docs.mencionai.com/mcp. Voltar ao hub MCP.

Antigravity

Arquivo global: ~/.gemini/config/mcp_config.json. Arquivo do workspace: .agents/mcp_config.json.

Stdio

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

Hospedado

Servidores remotos no Antigravity usam serverUrl, não url.

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

Residual do Gemini CLI

O Gemini CLI antigo ainda lê mcpServers em ~/.gemini/settings.json. Prefira o mcp_config.json do Antigravity acima.

URL curta: docs.mencionai.com/mcp. Voltar ao hub MCP.

n8n

O n8n é um cliente MCP HTTP. Ele não executa npx @mencionai/mcp. Não use o MCP Server Trigger do n8n para a MencionAI. Esse node expõe o n8n como servidor.

Use MCP Client Tool em um AI Agent, ou o node MCP Client.

Campos do node (v1.2+)

Campo	Valor
Server Transport	HTTP Streamable (`httpStreamable`)
MCP Endpoint URL / Endpoint	`https://mcp.mencionai.com/mcp`
Authentication	Bearer Auth
Token	Chave do Settings (`mak_live_…` ou `mak_test_…`)

Versões antigas do node usam SSE por padrão. O MCP hospedado da MencionAI é Streamable HTTP. Escolha HTTP Streamable.

n8n self-hosted só precisa de HTTPS de saída para mcp.mencionai.com. Opcional: OAuth2 MCP na mesma URL (discovery via WWW-Authenticate).

URL curta: docs.mencionai.com/mcp. Voltar ao hub MCP.