--- title: "Conectar um assistente de IA (MCP)" description: "Passo a passo para conectar um assistente de IA ao OneClick Ads via MCP: conexão por OAuth (login, como no conector do Claude) ou por chave de API no cabeçalho Authorization, com exemplo de curl." --- > Conecte um assistente de IA (como o **Claude**) aos seus dados do OneClick Ads e > faça perguntas em linguagem natural sobre campanhas, otimizações e conversões. O OneClick Ads oferece um **servidor MCP** (Model Context Protocol) — um endpoint que assistentes de IA entendem nativamente. Depois de conectado, o assistente pode consultar, por exemplo, suas contas de anúncios, campanhas, otimizações e os logs de conversão do OneClick Tracking. ## O endereço do servidor ``` https://mcp.oneclickads.com.br/mcp ``` Esse é o único endereço que você precisa informar ao seu assistente. Existem **duas formas** de autenticar a conexão. Escolha a que o seu aplicativo suporta: | Forma | Quando usar | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **OAuth (login)** | Aplicativos com suporte a conector MCP e login interativo — por exemplo, os apps do **Claude** (Claude.ai, Claude Desktop, Claude Code). | | **Chave de API (cabeçalho)** | Integrações que enviam um token fixo no cabeçalho `Authorization` — por exemplo, a **API do Claude** (parâmetro de conector MCP) ou agentes próprios em servidor. | --- ## Opção 1 — Conexão por OAuth (login) Indicada para clientes que abrem uma janela de login. É o caso dos conectores personalizados do Claude. Nesse fluxo você **não precisa gerar nenhuma chave**: o próprio aplicativo faz o login e pede a sua autorização. 1. No seu assistente, adicione um **conector/servidor MCP personalizado**. 2. Informe o endereço do servidor: `https://mcp.oneclickads.com.br/mcp`. 3. O aplicativo abrirá uma janela de **login do OneClick Ads**. Entre com a sua conta. 4. Revise e **autorize** os acessos solicitados (leitura e/ou escrita). 5. Pronto — a conexão fica salva no aplicativo e é renovada automaticamente. No caso do Claude, esse fluxo de OAuth é executado de ponta a ponta pelo próprio app. Para detalhes sobre o conector MCP do Claude, consulte a [documentação oficial da Anthropic](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector). Você pode acompanhar e revogar as conexões autorizadas a qualquer momento em [**Conexões → Apps conectados**](https://app.oneclickads.com.br/user/connections). --- ## Opção 2 — Conexão por chave de API (cabeçalho `Authorization`) Indicada para integrações que não fazem login interativo e enviam um token fixo no cabeçalho `Authorization: Bearer `. É a forma mais simples para agentes próprios e para a API do Claude. ### Passo 1 — Gere a sua chave de API 1. Acesse [**Conexões → Chaves de API**](https://app.oneclickads.com.br/user/connections) na sua conta OneClick Ads. 2. Escolha o escopo da chave: - **Somente leitura** (recomendado para começar) — consulta dados, sem alterar nada. - **Leitura e escrita** — permite também alterar otimizações e contas. 3. Clique em **Gerar chave** e **copie o token na hora** — ele aparece **uma única vez** e não pode ser recuperado depois. 4. Guarde o token como um **segredo** (cofre de senhas do aplicativo). Nunca cole em documentos, código ou conversas públicas. ### Passo 2 — Use a chave no cabeçalho Envie o token no cabeçalho `Authorization`: ``` Authorization: Bearer SUA_CHAVE_DE_API ``` ### Conectando pela API do Claude A API do Claude aceita servidores MCP que usam um token no cabeçalho. Informe o endereço do servidor e a sua chave de API no campo de autorização do conector: ```json { "mcp_servers": [ { "type": "url", "url": "https://mcp.oneclickads.com.br/mcp", "name": "oneclickads", "authorization_token": "SUA_CHAVE_DE_API" } ] } ``` O `authorization_token` é enviado pelo Claude como `Authorization: Bearer SUA_CHAVE_DE_API`. Veja os detalhes na [documentação do conector MCP do Claude](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector). --- ## Gerir vários clientes, cada um com a própria conta OneClick (agências) Se você é agência ou gestor de tráfego e cada cliente tem a **própria conta OneClick Ads**, a conexão é sempre **por login**: o assistente enxerga exatamente as contas de anúncios do login que autorizou a conexão. Para operar as contas de outro cliente, você troca **qual login** está conectado. - **Por OAuth (login):** cada conexão vale para **um login**. Para trocar de cliente, desconecte o conector e reconecte fazendo o login da conta OneClick **dele** (ou peça para o próprio cliente autorizar). Num mesmo app costuma haver **um conector por login** — para manter vários clientes ativos ao mesmo tempo, use logins/sessões separadas do assistente. - **Por chave de API:** gere **uma chave por cliente** (cada uma na conta OneClick do respectivo cliente) e aponte cada agente/sessão para a chave certa. É o caminho mais prático para automações que atendem várias contas. :::tip[Confirme em qual cliente você está] Antes de operar, confirme a conexão ativa: _"Claude, quais contas de anúncios eu enxergo agora?"_ — as contas listadas são as do login/chave conectado. Se aparecer o cliente errado, troque a conexão antes de qualquer ação de escrita. ::: :::note[Uma ação em várias contas do mesmo login é outra coisa] Aqui tratamos de clientes com **contas OneClick separadas**. Se as várias contas de anúncios estão **sob o mesmo login**, você não troca de conexão — basta pedir a ação para todas de uma vez. Veja [Editar campanhas, conjuntos e anúncios com IA](/pt-br/mcp/editar-campanhas-conjuntos-e-anuncios-com-ia/). ::: --- ## Testando a conexão com curl Para confirmar que a sua chave funciona, faça uma chamada de leitura. O comando abaixo lista as suas contas de anúncios Meta: ```bash curl https://mcp.oneclickads.com.br/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'Authorization: Bearer SUA_CHAVE_DE_API' \ --data '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "listMetaAdAccounts", "arguments": {} } }' ``` - **Com a chave correta**, a resposta traz os seus dados (status HTTP `200`). - **Sem a chave** (ou com uma chave inválida), a resposta é `401 Unauthorized`. - Com uma chave **somente leitura**, tentar uma ação de escrita retorna um erro indicando que a operação exige o escopo de escrita — exatamente o comportamento esperado. --- ## Por onde começar depois de conectar Conectou o assistente e não sabe por onde começar? Abra **Prompts**, no menu lateral do OneClick Ads (`app.oneclickads.com.br/prompts`). A página traz comandos prontos, organizados em quatro temas — entender a conta, otimizar campanhas, criativos e rastreamento — cada um com um botão de **copiar**. Cole no seu assistente e adapte os detalhes (nome da campanha, valores) antes de enviar. Se ainda não conectou nenhum assistente, a página mostra os mesmos prompts com um aviso e um atalho para [**Conexões**](https://app.oneclickads.com.br/user/connections) — dá para ver o que o assistente vai poder fazer antes mesmo de conectar. Para comandos de **ação** mais avançados (parametrizar em lote, criar campanhas por replicação), veja [Prompts prontos para operar campanhas](/pt-br/mcp/prompts-para-operar-campanhas/). --- ## Segurança e boas práticas - **Comece por leitura.** Conecte primeiro com escopo somente leitura, valide os dados e só depois considere a escrita. - **A escrita altera campanhas de verdade.** Ações como ativar/desativar otimizações mudam o comportamento real das suas campanhas. Use escopo de escrita apenas quando necessário e, de preferência, com confirmação humana antes de cada alteração. - **Trate a chave como uma senha.** Ela dá acesso à sua conta. Guarde-a apenas no cofre de segredos do aplicativo. - **Revogue quando quiser.** Se uma chave vazar ou não for mais usada, revogue-a em [**Conexões → Chaves de API**](https://app.oneclickads.com.br/user/connections) e gere uma nova. O mesmo vale para apps conectados por OAuth.