AdsAgent Meta MCP

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

Documentação

Plugin AdsAgent Tri-Channel

Plugin público do Claude + pacote de habilidades para o MCP hospedado tri-channel do AdsAgent: Meta, Google Ads e TikTok.

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

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

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

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

Versão atual do contrato: 0.7.64. O slug do plugin é adsagent (chave do marketplace adsagent). Novas conexões Meta usam o perfil de produto v2 por padrão; 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 do MCP.

O Que Isto É

Um pacote público de marketplace de plugin do Claude: habilidades 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 diz aos agentes quando tentar novamente, quando esperar e quando parar.
Uma distribuição versionada no GitHub para integração de usuários do AdsAgent e orientação de comportamento de agentes.
Um contrato de minimização de dados para agentes de IA que não devem escanear o AdsAgent como um banco de dados bruto.

O Que Isto Não É

Não é a listagem MCP do Diretório de Conectores da Anthropic (isso é registrado separadamente nos servidores hospedados).
Não é uma referência completa de ferramentas MCP.
Não é um SDK.
Não é um relé de transporte local.
Não é uma divulgação de rotas internas, esquemas, tabelas de banco de dados ou diagnósticos internos do 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 plugin, o prompt de instalação do painel do AdsAgent continua sendo o fallback manual:

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

Use esse prompt copiado somente quando você não estiver instalando o pacote de plugin do Claude. Este repositório ensina o comportamento do agente após a conexão MCP existir.

Habilidades Incluídas

Habilidade	Propósito
`adsagent-router`	Roteia solicitações do AdsAgent para fluxos de configuração, confiabilidade, insights ou copy.
`adsagent-setup`	Conecta pelo prompt de instalação do painel do AdsAgent e verifica a prontidão do Meta, Google Ads ou TikTok.
`adsagent-notifications`	Inspeciona e configura com segurança canais de notificação e Webhooks do Meta Ads.
`adsagent-reliability`	Respeita limites de nova tentativa, 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`	Faz perguntas de desempenho e MMP sem sobrecarregar o servidor.
`meta-copy`	Copia ou compara anúncios do Meta com confirmação e segurança de revisão do operador.
`google-ads-insights`	Faz perguntas sobre cliente, MCC, Search, PMax e desempenho do Google Ads por meio do MCP do Google Ads.
`tiktok-insights`	Lê o desempenho do TikTok e prepara com segurança fluxos nativos de criação de criativos, campanhas e conjuntos de anúncios.

Divulgação Progressiva

Os clientes de agentes carregam todas as descrições de Habilidades 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 de trabalho selecionado precisa desses detalhes.

Os arquivos em docs/ são documentação de produto e operação voltada a humanos. Eles não são contexto automático de agente e não fazem parte da travessia de referência de Habilidades. Os contratos de comportamento do 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 o 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 marcadores curtos. Se for necessária inspeção bruta forense, crie um repasse ao operador em vez de tornar linhas brutas a resposta do agente.

Política de Caixa Semipreta

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

Ler o guia MCP ao vivo do AdsAgent após conectar.
Usar as ferramentas disponíveis por meio da sessão MCP autenticada.
Evitar adivinhar campos de payload ocultos.
Evitar sondar solicitações rejeitadas.
Parar em respostas de revisão do operador e pedir ao operador do AdsAgent para inspecionar 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, confirmar antes de gravações e usar a integração fornecida pelo painel.

Fonte Oficial e Direitos

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

O pacote é proprietário e todos os direitos são reservados à adsagents LLC. A hospedagem pública no GitHub permite que pessoas visualizem e façam fork do repositório sob os Termos de Serviço do GitHub, mas um fork ou cópia local não concede nenhuma licença adicional de propriedade intelectual, exceto os direitos limitados de espelhamento no diretório de plugins do Anthropic Claude em LICENSE.md. Nenhuma outra permissão é concedida para redistribuir, espelhar, vender, sublicenciar, publicar versões modificadas, criar obras derivadas, treinar um produto concorrente a partir do pacote ou representar um fork como oficial. Consulte LICENSE.md e NOTICE.md.

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 estão 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 falha de forma fechada contra os três snapshots confirmados em contracts/manifests/. Cada snapshot é copiado byte a byte de um artefato de serviço confirmado e bloqueado 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 snapshots 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 exigida não comprovada, um resumo 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 do Claude adsagent (habilidades + 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 duplicadas local e de usuário, 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 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 cada servidor MCP mostrado em /mcp (Meta, Google, TikTok). Não adicione headers.Authorization a .mcp.json; o OAuth deve permanecer como caminho de autenticação.

Migrando de slugs de plugin legados

Instalações 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 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.

Em seguida, abra o AdsAgent somente se precisar de configuração OAuth/token do painel para clientes sem plugin:

Settings -> MCP Access -> Copy install prompt

Cole o prompt copiado em um novo chat quando o pacote de plugin não for usado. O prompt fornece URLs HTTP MCP hospedadas 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

Somente HTTP MCP hospedado.
Use https://adsagent.md/mcp/v2 para novas conexões Meta; /mcp é o fallback legado.
Não execute o código MCP do AdsAgent localmente.
Não use um relé local, a menos que o painel do AdsAgent diga explicitamente.
Armazene em cache a configuração de conexão onde 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.
Honre mcp_concurrency_limited com espera mais jitter.
Honre mcp_fanout_detected alternando para a ferramenta de visão geral em lote da plataforma em vez de tentar novamente a solicitação bloqueada de escopo único.
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 no 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 uma ausência no seletor 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 somente 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 de CSV bruto.
Faça polling do 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 aprovação explícita nova.
Faça polling das 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 de usuário.
Use tabelas Markdown para números.
Confirme antes da criação ou modificação de anúncios.
Use grouped_plan para múltiplas fontes de anúncios distintas; nunca o emule 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.