AdsAgent Meta MCP

https://adsagent.md/docs/mcp-onboarding

Documentação

Plugin AdsAgent Tri-Channel

Aqui, MCP significa Model Context Protocol (o padrão de chamada de ferramentas do Claude/Cursor). Não significa Multi-Channel Platform.

Pacote público de plugin + skills para Claude do MCP hospedado tri-canal da AdsAgent: Meta, Google Ads e TikTok.

Resumo de SEO para diretórios: AdsAgent é um Meta Ads MCP hospedado (Model Context Protocol) além de Google Ads e TikTok MCP — conecte Claude/Cursor via adsagent.md/connect.

Instalação:

Plugin Claude: claude plugin marketplace add adsagents/adsagent-ai-skills e depois claude plugin install adsagent@adsagent
Plugin Cursor: instale AdsAgent pelo Cursor Marketplace (o .cursor-plugin/ + mcp.json deste repositório)
Alternativa pelo painel: painel AdsAgent -> Configurações -> Acesso MCP -> Copiar prompt de instalação (clientes sem suporte a plugins)

Divisão de distribuição (importante):

Superfície	O que é	Está neste repositório?
Plugin Claude (marketplace auto-hospedado)	Skills + URLs MCP HTTP raiz `.mcp.json` (OAuth)	Sim
Plugin Cursor (manifesto de marketplace)	Skills + URLs MCP HTTP `mcp.json` (OAuth)	Sim
Diretório de Conectores da Anthropic	Apenas listagem do servidor MCP hospedado	Não — submissão separada em serviços `adsagent.md`

Repositório oficial no GitHub: github.com/adsagents/adsagent-ai-skills

Site: adsagent.md
Hub de links oficiais: adsagent.md/connect
Página do pacote de skills: adsagent.md/skills
Suporte: support@adsagent.md

Privacidade: Política de Privacidade da AdsAgent

Também listado no Product Hunt, Cursor Directory e MCP Market.

Versão atual do contrato: 0.7.72. O slug do plugin é adsagent (chave de marketplace adsagent). Novas conexões Meta usam por padrão o perfil de produto v2; os três endpoints hospedados negociam descoberta stateless moderna de MCP 2026-07-28 mantendo suporte a clientes legados de initialize.

O histórico de versões está em CHANGELOG.md.

O auxiliar local scripts/update_reminder.py compara versões semânticas estritas e armazena apenas estado limitado de versão/timestamp em $XDG_CACHE_HOME/adsagent-ai-skills/update-reminder-v1.json (ou ~/.cache/...). Falha de cache nunca bloqueia o trabalho MCP.

O Que Isto É

Um pacote público de marketplace de plugin Claude: skills de comportamento mais URLs MCP hospedadas via .mcp.json.
Um guia de comportamento para Claude Code, Cursor, Codex e outros clientes com suporte a MCP.
Uma camada de confiabilidade e segurança que orienta agentes sobre quando tentar novamente, quando aguardar e quando parar.
Uma distribuição versionada no GitHub para integração de usuários AdsAgent e orientação de comportamento de agentes.
Um contrato de minimização de dados para agentes de IA que não devem varrer a AdsAgent como um banco de dados bruto.
Opcionalmente, um AdsAgent Skill Pack (docs) stdio MCP implantável via Glama que lista e lê Markdown público skills/. Veja docs/glama-release.md.

O Que Isto Não É

Não é o backend MCP hospedado da AdsAgent para Meta, Google Ads ou TikTok. A imagem opcional Docker/Glama serve apenas os documentos públicos deste repositório; as ferramentas de anúncios permanecem nas URLs HTTP em mcp.json e exigem OAuth da AdsAgent.
Não é a listagem MCP do Diretório de Conectores da Anthropic (registrada separadamente nos servidores hospedados).
Não é uma referência completa de ferramentas MCP.
Não é um SDK.
Não é um relé de transporte local para APIs de anúncios.
Não é uma divulgação de rotas internas, esquemas, tabelas de banco de dados ou diagnósticos do backend da AdsAgent.

Para instalações do plugin Claude Code, a configuração OAuth MCP vem do .mcp.json deste repositório. Para clientes sem suporte a plugins, o prompt de instalação do painel AdsAgent continua sendo a alternativa manual:

AdsAgent dashboard -> Settings -> MCP Access -> Copy install prompt

Use esse prompt copiado apenas para uma conexão manual quando a conta expuser Acesso MCP. Plugins Claude instalados já incluem as três URLs. A skill de configuração orienta usuários desde uma conexão ausente até a autorização e sua tarefa publicitária original.

Conectar Após Instalar

Comece pelo canal que você precisa. Instalar o pacote de skills não autoriza uma conta publicitária, e uma tarefa Meta não exige configuração de Google ou TikTok.

Cliente	Conecte o canal solicitado
Claude web, Desktop ou Cowork	Abra Configurações -> Conectores e use a ação Conectar da conexão AdsAgent instalada. Se apenas skills foram instaladas, adicione um conector personalizado usando a URL hospedada abaixo. Complete o OAuth no navegador.
Claude Code	Abra `/mcp` e autentique o servidor incluído solicitado. Reutilize uma conexão existente.
Cursor	Autentique o servidor incluído solicitado nas configurações de MCP.
Outros clientes MCP	Adicione a URL HTTP hospedada solicitada com OAuth, ou use o prompt de instalação do painel da conta.

Canal	URL MCP hospedada
Meta	`https://adsagent.md/mcp/v2`
Google Ads	`https://google.adsagent.md/mcp`
TikTok	`https://tiktok.adsagent.md/mcp`

Depois pergunte: "Verifique minha conexão do Google Ads e me ajude a concluir qualquer autorização pendente, e mostre o desempenho da campanha de ontem." Substitua pelo seu canal e tarefa. A AdsAgent verifica esse canal, fornece um link no navegador quando necessário, aguarda você concluir e retoma a mesma tarefa. Para apenas uma verificação de conexão, ela informa o resultado sem iniciar um relatório.

Cada servidor tem sua própria autorização OAuth. Use o mesmo login AdsAgent no navegador e no cliente; nunca copie um token OAuth entre as três URLs. Autorização da plataforma e sincronização inicial de ativos/histórico são etapas separadas; "conectado" não significa que o histórico está carregado ou que os anúncios estão prontos para lançar.

Os controles de conexão do Claude estão documentados no guia oficial de conectores personalizados e no guia MCP do Claude Code.

Manifestos oficiais do Registro MCP

Três manifestos de servidores hospedados registram as entradas md.adsagent/* existentes no Registro MCP oficial, publicados pela primeira vez em 18/08/2026. A versão 1.0.0 foi verificada como ativa/mais recente em 09/10/2026; estes arquivos são instantâneos, não publicações pendentes. A inclusão de diretório pela primeira vez no GitHub permanece sob revisão manual. As skills públicas, guias e configurações de conexão são MIT; os backends publicitários hospedados são proprietários.

Skills Incluídas

Skill	Finalidade
`adsagent-router`	Roteia solicitações AdsAgent para fluxos de configuração, confiabilidade, insights ou copy.
`adsagent-setup`	Conecta o MCP solicitado, conclui a autorização da plataforma, verifica o escopo utilizável da conta e retoma a tarefa original.
`adsagent-notifications`	Inspeciona alertas, solicita atualização de alertas e explica MCP Events suportados ou integrações descontinuadas.
`adsagent-reliability`	Respeita limites de tentativas, backoff, renovação de sessão e concorrência.
`agent-scheduled-tasks`	Projeta, cria, verifica, atualiza, pausa e exclui tarefas agendadas de propriedade do agente sem confundir lembretes com prova de execução.
`meta-insights`	Responde perguntas de desempenho e MMP sem sobrecarregar o servidor.
`meta-copy`	Copia ou compara anúncios Meta com confirmação e segurança de revisão pelo operador.
`google-ads-insights`	Responde perguntas sobre cliente Google Ads, MCC, Search, PMax e desempenho via Google Ads MCP.
`tiktok-insights`	Lê desempenho do TikTok e prepara com segurança fluxos nativos de criação, campanha e grupo de anúncios.

Divulgação Progressiva

Clientes agente carregam todas as descrições de Skills para descoberta, mas devem carregar apenas o corpo do SKILL.md selecionado. Cada ponto de entrada é intencionalmente pequeno e vincula a arquivos de referência locais que são lidos somente quando o fluxo selecionado precisa desses detalhes.

Os arquivos em docs/ são documentação de produto e operação voltada a humanos. Não são contexto automático de agente e não fazem parte da travessia de referência de Skill. Os contratos de comportamento de agente estão em skills/ e são alcançados a partir do SKILL.md selecionado.

Contrato de Saída do Agente

Agentes que usam AdsAgent devem responder em Markdown por padrão:

## Answer
One-sentence answer.

## Scope
- Date:
- Entity:
- Grouping:
- Attribution / channel:

## Results
| Metric | Value |
| --- | ---: |

## Notes
- Data freshness:
- Limits or missing fields:
- Next safe action:

Não despeje JSON, CSV, diagnósticos ocultos, linhas brutas ou todos os campos retornados no chat. Limpe a resposta em tabelas voltadas ao operador e bullets curtos. Se inspeção forense bruta for necessária, crie um handoff para o operador em vez de tornar linhas brutas a resposta do agente.

Política de Caixa Semipreta

Este repositório documenta intencionalmente resultados e comportamento de agentes, não a interface interna completa. Agentes devem:

Usar skills instaladas para comportamento e esquemas de ferramentas MCP ao vivo para campos de solicitação. Nunca buscar instruções comportamentais remotas.
Usar ferramentas disponíveis por meio da sessão MCP autenticada.
Evitar adivinhar campos ocultos de payload.
Evitar sondar solicitações rejeitadas.
Parar em respostas de revisão do operador e pedir que o operador AdsAgent inspecione diagnósticos internos.
Usar o menor plano de dados seguro antes de fazer chamadas.
Preferir resumos agrupados e detalhamentos limpos em vez de linhas brutas.

O contrato externo do agente é: fazer perguntas claras, respeitar limites, seguir requisitos de aprovação divulgados e usar OAuth do cliente mais links de autorização de plataforma retornados.

Fonte Oficial e Direitos

Este repositório contém apenas o pacote de comportamento legível pelo cliente. O código-fonte do servidor AdsAgent, credenciais, esquemas, lógica de roteamento e diagnósticos operacionais não são distribuídos aqui.

Este pacote de skills é licenciado sob a Licença MIT. Veja LICENSE e NOTICE.md. Lançamentos oficiais vêm deste repositório; um fork ou pacote modificado não deve sugerir endosso, afiliação ou suporte da adsagents LLC.

Privacidade e efeitos no fluxo de trabalho

A Política de Privacidade da AdsAgent descreve a coleta, uso, retenção e processo de suporte de dados do serviço hospedado. O pacote contém instruções locais legíveis e três configurações MCP HTTPS; não contém credenciais OAuth e não instala agendador em segundo plano nem hooks. Autentique pelo fluxo OAuth do cliente MCP. Envie apenas parâmetros necessários para a tarefa publicitária selecionada pelo usuário. Não colete histórico de conversa, memórias, arquivos não relacionados ou credenciais para registro ou diagnóstico.

A orientação do Google Ads cobre leituras. As capacidades de Meta e TikTok variam por conta e ferramenta divulgada. Mutações publicitárias usam o contrato de aprovação do servidor; operações diretas no workspace explicitamente solicitadas seguem seu próprio contrato de ferramenta. A preparação de criativos pode enviar mídia antes da confirmação publicitária final. Uma verificação autorizada de notificações altera alertas e pode gerar MCP Events para assinaturas existentes. O Meta atual não configura mais e-mail, Feishu, Telegram ou Webhooks de Meta Ads por meio deste pacote. Fluxos agendados usam um agendador disponível no host e exigem intenção do usuário.

Exemplos de Prompts

Use AdsAgent to list my connected Meta products, Google Ads customers, or TikTok advertisers, then ask which scope's today data I want to inspect.

For Google Ads, inspect agent_method_profile, pick an enabled non-manager customer, and use one cached insights_query_consistent request when the profile is advertised.

For TikTok, inspect agent_method_profile and use one insights_query_consistent scopes request when advertised; otherwise use the native batch overview fallback.

Prepare a copy of this winning Meta ad into the target account, but ask me for confirmation before creating anything.

Group these distinct Meta Ads by language into the requested Campaign and AdSet layout. Prepare one grouped_plan, show every settings_source_ad_id and geography override, and wait for my approval before confirming once.

Mais exemplos em docs/examples.md.

Validação

Execute o contrato de lançamento local e os testes:

python scripts/validate_tri_channel_pack.py
python -m pytest -q

A validação de lançamento é fail-closed contra os três instantâneos confirmados em contracts/manifests/. Cada instantâneo é copiado byte a byte de um artefato de serviço confirmado e travado em seu canal, revisão de origem, caminho público do artefato, metadados e SHA-256 em contracts/manifests/provenance.json. O CI não faz solicitações de rede ao vivo.

python scripts/validate_public_tool_manifests.py

Um operador pode atualizar deterministicamente os três instantâneos após a mudança do manifesto do serviço. O comando rejeita fontes não confirmadas, sujas, ausentes ou incompatíveis com o contrato e nunca busca da rede:

python scripts/sync_public_tool_manifests.py \
  --source meta=/path/to/meta-tools.json \
  --source google=/path/to/google-tools.json \
  --source tiktok=/path/to/tiktok-tools.json

Todas as três fontes são obrigatórias. Uma ferramenta referenciada ausente, uma capacidade ou porta não comprovada, um digest de proveniência desatualizado ou um canal ausente falham na validação de lançamento. --allow-missing existe apenas para diagnósticos locais explícitos e não é usado pelo CI de lançamento.

Instalação

Este repositório é distribuído como o plugin Claude adsagent (skills + URLs MCP .mcp.json). O nome do repositório no GitHub permanece adsagent-ai-skills.

Claude Code (recomendado)

claude plugin marketplace add adsagents/adsagent-ai-skills
claude plugin install adsagent@adsagent

Atualize uma instalação existente no escopo do usuário:

claude plugin update --scope user adsagent@adsagent

Se claude plugin list mostrar instalações locais e de usuário duplicadas, mantenha o escopo do usuário:

claude plugin uninstall --scope local adsagent@adsagent

Inicie uma nova sessão do Claude Code após instalar ou atualizar.

Pré-instalação em Cloud / Cowork (trecho de configurações)

{
  "extraKnownMarketplaces": {
    "adsagent": {
      "source": {
        "source": "github",
        "repo": "adsagents/adsagent-ai-skills"
      }
    }
  },
  "enabledPlugins": ["adsagent@adsagent"]
}

Após a instalação, autentique apenas os servidores MCP necessários para a sua tarefa. No Claude Code, use /mcp; no Claude web/Desktop ou Cowork, use Configurações -> Conectores. Não adicione headers.Authorization a .mcp.json; o OAuth deve permanecer como o caminho de autenticação.

Migrando de slugs de plugins legados

Instalações mais antigas usavam adsagent-ai-skills@adsagent-ai-skills ou adsagent-meta-ai-skills@adsagent-meta-ai-skills. O marketplace declara uma renomeação para adsagent@adsagent. Após migrar, remova duplicatas legadas:

claude plugin uninstall --scope user adsagent-ai-skills@adsagent-ai-skills
claude plugin uninstall --scope user adsagent-meta-ai-skills@adsagent-meta-ai-skills

Codex CLI

codex plugin marketplace add adsagents/adsagent-ai-skills
codex plugin add adsagent@adsagent

Atualize:

codex plugin marketplace upgrade adsagent

Inicie uma nova sessão do Codex após instalar ou atualizar.

Fallback via Git e outros clientes compatíveis com Agent-Skills

As habilidades em skills/ usam o layout padrão de Agent Skills (skills/<name>/SKILL.md com frontmatter YAML). Clientes que apenas consomem habilidades (sem o pacote MCP do plugin) podem clonar manualmente:

git clone https://github.com/adsagents/adsagent-ai-skills.git ~/.codex/skills/adsagent-ai-skills

Esses clientes ainda precisam de uma conexão MCP separada (prompt de instalação do painel ou Diretório de Conectores). O caminho do plugin é o pacote de habilidades + MCP em uma única etapa.

Para um cliente manual, use OAuth hospedado ou, quando disponível para a sua conta, o prompt de instalação do painel do AdsAgent:

Settings -> MCP Access -> Copy install prompt

Cole o prompt copiado em uma nova conversa quando o pacote do plugin não for usado. O prompt fornece URLs MCP HTTP hospedados para:

Meta default: https://adsagent.md/mcp/v2
Meta legacy fallback: https://adsagent.md/mcp
Google Ads: https://google.adsagent.md/mcp
TikTok: https://tiktok.adsagent.md/mcp

Regras Importantes de Execução

Use apenas MCP HTTP hospedado para trabalho com anúncios.
Use https://adsagent.md/mcp/v2 para novas conexões Meta; /mcp é o fallback legado.
Não execute nem retransmita o MCP de anúncios AdsAgent hospedado localmente. A imagem opcional skill_pack_mcp é um leitor apenas de documentação deste repositório; não é um backend de anúncios.
Não use um relay local, a menos que o painel do AdsAgent diga explicitamente para fazer isso.
Armazene em cache a configuração da conexão quando o cliente suportar.
Mantenha a concorrência MCP por token limitada.
Respeite Retry-After.
Analise Retry-After do cabeçalho HTTP, do data de nível superior ou do error.data JSON-RPC.
Respeite mcp_concurrency_limited com espera e jitter.
Respeite mcp_fanout_detected alternando para a ferramenta de visão geral de lote da plataforma em vez de tentar novamente a solicitação de escopo único bloqueada.
Quando agent_method_profile.profile_id=adsagent_agent_methods_v1 e sua leitura consistente estiverem presentes no catálogo local do cliente, use uma solicitação insights_query_consistent com scope ou scopes ordenado para todas as três plataformas.
Sem esse perfil, ou quando sua leitura anunciada estiver ausente apenas no catálogo local do cliente, use o fallback nativo nomeado do perfil ou as ferramentas documentadas do lado do servidor: Meta/TikTok insights_query_batch_overview, Google google_ads_insights_overview_batch. Não relate uma falha de registro do servidor por causa de uma falha de seleção local.
Consulte dados agregados primeiro e nunca infira paridade de capacidade entre plataformas a partir de um nome de ferramenta compartilhado.
Relate totais calculados pelo servidor a partir da resposta; não some linhas atualmente visíveis.
Confie nos totais apenas quando meta.complete=true; escopos ausentes são desconhecidos, nunca zero.
Faça polling de tarefas na fila até terminal=true e retorne o link do artefato em vez do CSV bruto.
Faça polling de trabalho na fila diretamente com tasks_get_status(task_ref=...) quando o servidor anunciar referências diretas de tarefas.
Os tokens de confirmação do QuickCreate são de uso único e expiram após 15 minutos. Verifique expires_at; após confirm_token_invalid, prepare novamente, mostre o novo resumo e obtenha nova aprovação explícita.
Faça polling de tarefas de criação do Meta com tasks_get_status(task_ref=..., response_mode=compact). Em no_create_permission, direcione o usuário para /dashboard/assets/fb-users; nunca altere permissões do cliente nem reproduza a criação falhada automaticamente.
Evite leituras de linhas brutas em conversas normais com usuários.
Use tabelas Markdown para números.
Confirme antes da criação ou modificação de anúncios.
Use grouped_plan para múltiplos Ads de origem distintos; nunca emule isso por meio de uma série de mutações de cópia no lado do cliente.
Pare em erros de revisão do operador.
Quando um erro incluir support_ref, preserve-o e mostre-o literalmente para suporte. Não é autorização; nunca invente, modifique, enumere ou substitua por tokens, corpos de solicitação ou logs.

Glama / Docker docs MCP

O Dockerfile raiz compila o AdsAgent Skill Pack (docs) — um MCP stdio que expõe list_skills, get_skill, get_hosted_mcp_urls e get_pack_readme. O Glama Build → Make Release pontua esse servidor de docs. Ele não substitui https://adsagent.md/mcp/v2, https://google.adsagent.md/mcp ou https://tiktok.adsagent.md/mcp. Detalhes: docs/glama-release.md.

Licença

MIT. Veja LICENSE.