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):

• docs.mencionai.com/mcp
• docs.mencionai.com/api
• docs.mencionai.com/sdk

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

1. Crie uma chave em Settings → API Keys (mak_live_… ou mak_test_…).
2. Instale Node.js 20+ (stdio local). n8n não precisa disso: fala com o MCP hospedado via HTTP.
3. 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:

1. list_workspaces
2. get_visibility_overview
3. explain_visibility_gaps / compare_competitors
4. Prompts: list_prompts → analyze_prompt. add_prompt acompanha uma pergunta. update_prompt edita o texto ou define is_active.
5. “O que fazer?”: analyze_action_plan depois analyze_sources
6. Briefing semanal: analyze_weekly_report · pontuação de recomendação de IA: analyze_ai_recommendation_score
7. 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.
8. 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

• Primeiros passos com a API
• SDK TypeScript

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

1. Abra Plugins.
2. Busque MencionAI e instale.
3. Quando uma tool rodar, entre em www.mencionai.com e autorize o app.
4. 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.

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

https://mcp.mencionai.com/mcp

3. Na primeira tool, entre em www.mencionai.com e autorize o app.
4. 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.