Ads Manager MCP — Documentação de Integração

Documentação pública para conectar Claude, Cursor e outros clientes MCP ao Ads Manager.

URL do servidor: https://mcp.adsmanager.com.br/mcp
Documentação online: https://adsmanager.com.br/docs/mcp
Health: https://mcp.adsmanager.com.br/health

1. O que é

O MCP (Model Context Protocol) do Ads Manager expõe tools de leitura e operação sobre Google Ads, Meta Ads e LinkedIn Ads, isoladas por agência (tenant).

Cada usuário do tenant gera os próprios tokens adsm_* em Configurações → API / MCP. O Claude (ou Cursor) envia esse token no header; o servidor só enxerga clientes e contas da agência, e todas as ações ficam gravadas em mcp_action_log com user_id, e-mail e nome de quem possui o token.

2. Autenticação

Authorization: Bearer adsm_<seu_token>

Como gerar o token (por usuário)

Entre no Ads Manager com sua conta da agência (qualquer membro do tenant).
Vá em Configurações → API / MCP.
Clique em Criar Novo Token.
Marque MCP / Claude completo (inclui write:google, write:meta, write:linkedin).
Copie o token — ele só aparece uma vez.
Ações feitas com esse token aparecem no Log de ações MCP (e na coleção MongoDB mcp_action_log) atribuídas a você.

Scopes

| Scope | Uso | |-------|-----| | mcp:tools / read:* | Listar clientes, contas, métricas, análises | | write:google | Pausar/criar/ajustar Google Ads | | write:meta | Pausar/criar/ajustar Meta Ads | | write:linkedin | Pausar/criar/ajustar LinkedIn Ads |

3. Claude (Custom Connector)

Em Claude: Customize → Connectors → Add custom connector.
URL: https://mcp.adsmanager.com.br/mcp
Authentication: No sign in
Request headers:
- Nome: Authorization
- Valor: Bearer adsm_SEU_TOKEN
Salve e ative o connector na conversa.

4. Cursor

No mcp.json / settings MCP:

{
  "mcpServers": {
    "adsmanager": {
      "url": "https://mcp.adsmanager.com.br/mcp",
      "headers": {
        "Authorization": "Bearer adsm_SEU_TOKEN"
      }
    }
  }
}

5. Tools principais

Use sempre list_agency_ad_accounts (ou list_agency_clients) antes de mutações.

Conta / tenant

mcp_whoami — agency_id e permissões do token
list_agency_clients
list_agency_ad_accounts

Google Ads

Performance, listagem API, pause/resume, budget, create search, duplicate, negativas, audiências, sync

Meta Ads

Performance, listagens (com soft-sync de estrutura), pause/resume campanha/adset/ad, smart create/duplicate, audiências, placement, frequência

LinkedIn Ads

Overview, performance, listagem API, pause/resume, budget, create_linkedin_campaign (PAUSED)

Funil

get_client_funnel, analyze_funnel_bottleneck, suggest_funnel_audiences, create_funnel_from_template

Mutações alteram campanhas reais. Em testes, use contas de homologação e status PAUSED.

6. Teste rápido (SDK) e e2e por IA

export ADSM_MCP_TOKEN=adsm_...
python cli/mcp_sim_client.py --url https://mcp.adsmanager.com.br/mcp

Bateria de create (PAUSED) + loop OpenAI:

export ADSM_MCP_TOKEN=adsm_...
export MCP_HOMOLOG_GOOGLE_ACCOUNT=...
export MCP_HOMOLOG_LINKEDIN_ACCOUNT=...   # opcional
python cli/mcp_ai_battery.py --url https://mcp.adsmanager.com.br/mcp
python cli/mcp_ai_e2e.py --url https://mcp.adsmanager.com.br/mcp

Relatórios em docs/superpowers/reports/mcp-ai-*.json. Cada tool fica em mcp_action_log com o user_id do dono do token.

7. Segurança e auditoria

Token isolado por agency_id — não cruza tenants.
Token ligado a user_id — cada membro cria e gerencia os seus.
Auditoria completa em MongoDB mcp_action_log (agency_id, user_id, user_email, user_name, token_id, tool_name, argumentos sanitizados, resultado, sucesso, latência).
Revogue em Configurações → API / MCP a qualquer momento.
Não commite o token em repositórios.
Prefira token só-leitura se o Claude for apenas analítico.

8. API REST (complementar)

Além do MCP, existe a API REST v1:
https://adsmanager.com.br/api/docs

Suporte

Dúvidas de integração: suporte da sua agência no Ads Manager ou equipe Kaizen.

MCP — Integração Claude / Cursor