Adstudio

npx add-mcp 'https://useadstudio.com/api/mcp'

Servidor MCP Adstudio

Conecte ChatGPT, Claude, Muse ou qualquer cliente MCP às suas contas de anúncios por meio do servidor MCP somente leitura do Adstudio.

O Adstudio MCP é um servidor Model Context Protocol hospedado. Ele permite que um assistente de IA que você já usa leia os dados de publicidade conectados aos seus espaços de trabalho do Adstudio e responda perguntas como "por que o CPA saltou na semana passada?" com números reais das suas contas.

Endpoint	https://useadstudio.com/api/mcp
Transporte	HTTP Streamable (MCP 2025-06-18)
Autenticação	OAuth 2.1 com PKCE, registro dinâmico de cliente, rotação de token de atualização
Plataformas disponíveis hoje	Google Ads, Meta Ads, TikTok Ads
Acesso	Somente leitura. Nenhuma ferramenta pode alterar qualquer coisa em uma conta de anúncios.

Como funciona

As contas do Google Ads, Meta Ads e TikTok Ads são conectadas uma vez, em **Configurações → Integrações**, exatamente como no restante do produto. O servidor MCP nunca solicita credenciais de plataforma por conta própria. Em **Configurações → MCP**, você cria uma conexão pessoal. Ela alcança todos os espaços de trabalho aos quais você pertence, incluindo aqueles que você entrar depois, e mostra um alternador **Leitura** e **Escrita** por plataforma para cada espaço de trabalho. Somente o que você ativar fica acessível; a escrita ainda não é exposta por nenhuma ferramenta; o alternador apenas registra a intenção para versões futuras. Adicione `https://useadstudio.com/api/mcp` no ChatGPT, Claude, Muse ou qualquer cliente MCP. O cliente descobre o servidor de autorização do Adstudio, você faz login no Adstudio no navegador e aprova a conexão. Consulte [Conectar um cliente](#connect-a-client). O assistente primeiro lista suas contas e, em seguida, nomeia um espaço de trabalho, plataforma e conta explícitos em cada chamada. Nada é inferido ou definido por padrão. Consulte [Ferramentas](#tools) para saber o que ele pode recuperar.

O que o assistente pode fazer

• Descobrir escopo: os espaços de trabalho aos quais você pertence, as plataformas conectadas em cada um, a conta de anúncios selecionada e se a leitura é permitida lá.
• Consultar desempenho: gastos, impressões, cliques, conversões, valor de conversão, parcela de impressões, alcance, frequência, CPM, CTR, CPC e métricas de vídeo no nível de conta, campanha, grupo de anúncios, conjunto de anúncios ou anúncio, com um período de comparação e um detalhamento (data, dispositivo, posicionamento, plataforma do editor, posição, idade, gênero).
• Navegar pela estrutura: campanhas, grupos de anúncios, conjuntos de anúncios e anúncios com status e tipo, sem métricas.
• Revisar criativos: títulos, texto do corpo, descrições, mídia, URLs de destino e recursos de automação para qualquer escopo.

Cada resposta traz procedência (fonte, horário da recuperação, moeda, período, fuso horário, modelo de atribuição) e uma lista não resolvida nomeando qualquer coisa que não pôde ser recuperada e o motivo. O assistente nunca precisa adivinhar.

Permissões e segurança

• Uma conexão pertence a uma pessoa, não a um espaço de trabalho, e nunca pode exceder a função dessa pessoa. Membros leem; administradores podem adicionalmente conceder alternadores de escrita.
• O escopo é relido a cada solicitação. Retirar uma permissão em Configurações → MCP tem efeito na próxima chamada, não na expiração do token.
• Revogar em Configurações → MCP corta o acesso de todos os clientes imediatamente.
• Texto escrito fora do Adstudio (nomes de contas, nomes de campanhas, texto de anúncios, termos de pesquisa) é retornado marcado como conteúdo não confiável, para que um cliente possa tratá-lo como dados em vez de instruções.
• O Adstudio divulga apenas os dados que você solicita, ao cliente que você autorizou, e nunca envia credenciais OAuth da plataforma ao cliente. Consulte a política de privacidade.

Limites

• Apenas Google Ads, Meta Ads e TikTok Ads. Solicitações para qualquer outra plataforma são recusadas com um motivo explícito; plataformas adicionais são adicionadas conforme são verificadas.
• Uma conta de anúncios selecionada por plataforma por espaço de trabalho, a selecionada no Adstudio.
• query_performance e get_entities retornam no máximo 500 linhas por chamada, get_creatives no máximo 100. As respostas informam quando foram truncadas e como ampliar a consulta.
• Limites de taxa se aplicam por espaço de trabalho e no endpoint de registro. O uso interativo não os alcança.

Conectar um cliente

Antes de começar

1. Pelo menos uma conta do Google Ads, Meta Ads ou TikTok Ads está conectada em um espaço de trabalho do Adstudio ao qual você pertence (Configurações → Integrações).
2. Você criou sua conexão em Configurações → MCP e ativou Leitura para essa plataforma nesse espaço de trabalho. A autorização é recusada até que uma conexão exista, para que nenhum cliente possa escolher silenciosamente suas permissões por você.

O endereço é sempre o mesmo e não contém segredo:

https://useadstudio.com/api/mcp

ChatGPT

No ChatGPT, abra **Configurações → Apps e Conectores** (ou **Plugins**) e pesquise por **Adstudio**. Se você estiver adicionando como um conector personalizado no modo de desenvolvedor, cole o endpoint acima. O ChatGPT abre a página de login do Adstudio. Entre com sua conta do Adstudio e aprove a conexão. Comece com *"Liste minhas contas de anúncios no Adstudio"* e depois pergunte sobre desempenho, estrutura ou criativos da conta que você nomear.

Claude

No Claude, abra **Configurações → Conectores → Adicionar conector personalizado**, nomeie-o como Adstudio e cole o endpoint acima. O Claude descobre o servidor de autorização do Adstudio automaticamente, registra-se e abre a página de login. Aprove a conexão. Ative o conector Adstudio no menu de ferramentas de uma conversa e pergunte.

Muse e outros clientes MCP

Qualquer cliente que suporte servidores MCP remotos via HTTP Streamable com OAuth 2.1 funciona da mesma forma: adicione o endpoint, conclua o login no navegador, pergunte. Clientes que suportam apenas servidores stdio precisam de uma ponte como mcp-remote:

{
  "mcpServers": {
    "adstudio": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://useadstudio.com/api/mcp"]
    }
  }
}

Conectar uma plataforma específica

Páginas passo a passo para cada par de plataforma de anúncios e cliente de IA:

Plataforma	ChatGPT	Claude	Gemini	Cursor
Google Ads	Guia	Guia	Guia	Guia
Meta Ads (Facebook e Instagram)	Guia	Guia	Guia	Guia
TikTok Ads	Guia	Guia	Guia	Guia
ChatGPT Ads	Guia	Guia	Guia	Guia
DV360	Guia	Guia	Guia	Guia
Pinterest Ads	Guia	Guia	Guia	Guia
Shopify	Guia	Guia	Guia	Guia

Endpoints de descoberta

Os clientes MCP os encontram por conta própria; eles estão listados para operadores que precisam colocá-los na lista de permissões ou depurá-los.

Finalidade	URL
Metadados de recurso protegido (RFC 9728)	https://useadstudio.com/.well-known/oauth-protected-resource/api/mcp
Metadados do servidor de autorização (RFC 8414)	https://useadstudio.com/.well-known/oauth-authorization-server
Autorização	https://useadstudio.com/api/mcp/oauth/authorize
Token	https://useadstudio.com/api/mcp/oauth/token
Registro dinâmico de cliente (RFC 7591)	https://useadstudio.com/api/mcp/oauth/register

As URIs de redirecionamento devem ser URLs https:// exatas ou um host de loopback. Os tokens de acesso têm vida curta; os tokens de atualização giram a cada uso.

Solução de problemas

Os documentos de metadados acima devem responder sem uma sessão. Se sua rede usar proxy `useadstudio.com`, certifique-se de que `/.well-known/*` e `/api/mcp/*` estejam acessíveis sem autenticação. Você ainda não criou uma conexão. Abra **Configurações → MCP** no Adstudio, crie uma, ative Leitura para as plataformas necessárias e tente novamente o cliente. A leitura está desativada para essa plataforma nesse espaço de trabalho, ou sua função não permite. A resposta informa qual. Ative-a em Configurações → MCP. A API da plataforma não pôde responder. Verifique a integração em **Configurações → Integrações** (tokens expirados mostram um banner de reconexão) e tente novamente. **Configurações → MCP → Revogar**. Todo cliente perde o acesso na próxima solicitação. Crie uma nova conexão para reconectar.

Ainda com problemas? Use a página de suporte. Nunca cole tokens ou o valor do desafio em uma solicitação de suporte.

Ferramentas

Todas as cinco ferramentas são somente leitura. Toda ferramenta, exceto list_accounts, exige um workspaceId, platform explícito (google_ads, meta_ads ou tiktok_ads) e accountId; o servidor nunca os define por padrão. Toda resposta tem o mesmo envelope:

{
  "data": { "status": "ok", "...": "..." },
  "provenance": { "source": "platform_api", "retrievedAt": "...", "currency": "TRY", "period": { "start": "...", "end": "...", "timezone": "Europe/Istanbul" }, "attribution": "..." },
  "unresolved": [ { "subject": "...", "kind": "could_not_look", "reason": "...", "remedy": "..." } ]
}

Valores escritos fora do Adstudio (nomes de contas e campanhas, texto de anúncios, termos de pesquisa) são envolvidos como { "untrusted": true, "value": "..." }.

list_accounts

Lista todos os espaços de trabalho que a conexão alcança, as plataformas conectadas em cada um, a conta selecionada por plataforma e se leitura e escrita são permitidas lá, com o motivo quando negado. Não aceita argumentos e não faz chamada à API da plataforma. Sempre a primeira chamada.

describe_capabilities

Para uma conta, retorna os níveis, métricas, detalhamentos, filtros e limites que query_performance aceita lá, e o que get_entities e get_creatives podem retornar. Chame-a antes da primeira consulta contra uma conta.

Argumento	Obrigatório	Observações
workspaceId, platform, accountId	sim	De list_accounts

query_performance

Linhas de desempenho atribuído para um intervalo de datas.

Argumento	Obrigatório	Observações
workspaceId, platform, accountId	sim
level	sim	account, campaign, ad_group (Google, TikTok), ad_set (Meta), ad
start, end	sim	YYYY-MM-DD, no fuso horário de relatórios da conta
metrics	sim	Pelo menos um. Google: impressions, clicks, spend, conversions, conversion_value, além de search_impression_share, search_budget_lost_impression_share, search_rank_lost_impression_share no nível de campanha. Meta adiciona reach, frequency, cpm, ctr, cpc, video_plays, video_thruplays, video_p25 … video_p100. TikTok expõe o mesmo conjunto que Meta; conversions é o evento de otimização do TikTok conversion, conversion_value é o valor de compra na web e video_thruplays são visualizações de 6 segundos.
comparison	não	{ "start", "end" } para um segundo período; as linhas voltam com comparisonMetrics
breakdowns	não	No máximo um: date, device, placement, publisher_platform, platform_position, age, gender. TikTok: date, age, gender, placement, device (iOS / Android / PC); conversion_value não está disponível com os últimos quatro
filters	não	[{ "field": "entity_id", "value": "<id>" }]; não permitido no nível de conta
sort	não	{ "field", "direction" }
limit	não	1–500

O Google Ads retorna apenas contagens brutas; derive CTR, CPC, CPA e ROAS a partir delas. O Meta relata conversões com as janelas de atribuição padrão da conta e nomeia a definição de conversão na resposta.

get_entities

A hierarquia atual para um nível, sem métricas: id, nome, status e tipo do provedor, além do pai quando parentId é fornecido.

Argumento	Obrigatório	Notas
workspaceId, platform, accountId	sim
level	sim	campaign, ad_group, ad_set, ad
parentId	não	ID do pai imediato, por exemplo, um ID de campanha ao listar conjuntos de anúncios ou grupos de anúncios
limit	não	1–500

get_creatives

Atribuições de anúncio a criativos com texto normalizado (títulos, corpos, descrições, caminhos, nomes de empresas, chamadas para ação), mídia, URLs de destino e recursos de automação habilitados. Sem métricas; junte com query_performance no nível de ad para classificar criativos.

Argumento	Obrigatório	Notas
workspaceId, platform, accountId	sim
scopeLevel	sim	account, campaign, ad_group, ad_set, ad
entityId	no escopo não-conta	O ID da campanha, grupo de anúncios, conjunto de anúncios ou anúncio
limit	não	1–100

Exemplos de prompts

• "Como minhas campanhas do Google Ads performaram na semana passada em comparação com a semana anterior?"
• "Dê-me um resumo mensal da minha conta do Meta Ads com gastos, conversões, CPA e ROAS em relação ao mês anterior."
• "Por que o CPA da minha campanha de Brand Search aumentou nos últimos 14 dias?"
• "Quais anúncios na minha conta do Meta Ads estão mostrando sinais de fadiga criativa agora?"
• "Classifique os anúncios da minha campanha de Summer Sale por ROAS e mostre-me o que os três primeiros dizem."
• "Detalhe meus gastos do Meta Ads por posicionamento nos últimos 30 dias."

O que as ferramentas não farão

• Alterar orçamentos, status, lances, segmentação ou criativos. Solicitações para isso são respondidas com o limite somente leitura.
• Consultar OpenAI Ads, DV360, Adjust, GA4 ou Search Console via MCP ainda, mesmo que estejam conectados no Adstudio.
• Adivinhar um workspace, conta, moeda ou fuso horário.

Esta documentação é construída e hospedada no Mintlify, uma plataforma de documentação para desenvolvedores.