Conectar o Vyper a um cliente de IA por MCP

O MCP permite que um cliente compatível, como Claude ou Codex, consulte informações da sua empresa no Vyper. A análise é gerada pelo cliente de IA; o Vyper fornece dados e definições, não um chatbot próprio.

Antes de conectar

O proprietário da empresa administra os tokens MCP. Confira a empresa ativa antes de gerar uma credencial.

O token fica vinculado à empresa selecionada ao criá-lo. Ele não permite consultar outras empresas, mesmo que você também tenha acesso a elas. Trocar de empresa no Vyper não altera o alcance de um token existente.

Criar e proteger um token

1. Confira a empresa ativa e abra MCP.
2. Use um nome que identifique o cliente, por exemplo, Meu cliente de desktop.
3. Selecione uma validade de 7, 30 ou 90 dias e gere o token.
4. Copie-o diretamente para o campo seguro de configuração do cliente. Ele só aparece ao ser criado; não poderá ser recuperado depois.
5. Confirme que o guardou. Você pode manter até três tokens ativos por proprietário e empresa.

Um novo token permite consultas de leitura. A permissão para propor alterações na Meta é habilitada separadamente e não permite executá-las sem aprovação humana.

Não cole o token em conversas com a IA, capturas, documentos compartilhados ou e-mails para suporte. Não use seu token da Meta como token MCP. Os dois acessos têm finalidades diferentes.

Conectar um cliente compatível

O endereço do servidor é:

https://vyper.digital/api/mcp

O cliente deve aceitar um servidor HTTP MCP e enviar o token pelo cabeçalho Authorization, com o valor Bearer seguido de um espaço e do token. Não adicione o token à URL.

Claude

Em Personalizar → Conectores, adicione um conector personalizado com a URL acima. Em Request headers, configure Authorization com o valor indicado. Ative as ferramentas do Vyper na conversa. Se o fluxo tentar iniciar sessão por OAuth, revise a configuração: esta conexão usa um token fixo.

Use um conector pessoal. Em conectores compartilhados de Team ou Enterprise, uma credencial fixa pode dar aos outros membros o mesmo acesso; não compartilhe ali seu token da empresa. Consulte o guia oficial do Claude.

Codex

Configure uma variável de ambiente chamada VYPER_MCP_TOKEN com seu token no ambiente que inicia o Codex. Adicione esta configuração a ~/.codex/config.toml, sem escrever o segredo no arquivo:

[mcp_servers.vyper]
url = "https://vyper.digital/api/mcp"
bearer_token_env_var = "VYPER_MCP_TOKEN"

Reinicie o cliente se necessário para carregar a configuração e a variável. Se o abrir por um ícone, confira se esse processo recebe a variável; defini-la em outro terminal não garante que o aplicativo a herde. A conexão é autenticada pelo token, não por login OAuth. Consulte a configuração oficial de servidores HTTP MCP.

O que você pode consultar

Exemplos de perguntas, com nomes fictícios:

• «Compare os últimos sete dias da minha Oferta exemplo com os sete anteriores; informe as datas e os dados incompletos».
• «Detalhe as vendas de ontem por país e webhook, separando valores pendentes».
• «Mostre investimento e vendas atribuídas por anúncio da Oferta exemplo, com evolução diária».
• «Liste todas as minhas campanhas ativas importadas, mesmo sem gasto hoje».

Os relatórios aceitam períodos de até 31 dias. O relatório de vendas aceita até quatro dimensões de agrupamento e 10.000 registros de origem por período; acima desse limite, reduza as datas ou selecione oferta/fonte. Se houver outras páginas, o cliente deve consultá-las antes de afirmar que mostrou tudo. Não deve somar novamente os totais gerais repetidos em cada página.

Interpretar os resultados

• As métricas são consultadas nos dados salvos no Vyper; o MCP não sincroniza a Meta nem recupera vendas que nunca chegaram.
• Uma lista importada de campanhas ativas não garante que a Meta esteja entregando anúncios agora. A consulta de controles verifica a configuração atual na Meta, não sua entrega efetiva.
• A atribuição e a conversão de moeda seguem as mesmas regras do dashboard. Um identificador desconhecido não se transforma sozinho em venda atribuída.
• Parcial, valor pendente ou dado indisponível não significam zero. Um resultado completo dos registros disponíveis não comprova que todas as vendas do sistema emissor chegaram.
• O dia atual está aberto. Duas consultas separadas podem diferir se chegaram vendas ou houve uma sincronização entre elas.

Propor uma alteração na Meta

1. Habilite explicitamente as propostas para o token desejado no Vyper.
2. Atualize as ferramentas disponíveis no seu cliente de IA.
3. Solicite uma proposta para pausar, ativar ou ajustar um orçamento diário de uma campanha ou conjunto da sua oferta.
4. Confira entidade, conta, moeda e valores anterior e novo. Abra o link de aprovação retornado e confirme dentro da sua sessão no Vyper.

Uma proposta pendente não modifica a Meta. Dizer «sim» no chat não a executa. Somente o mesmo proprietário que originou a proposta pode aprová-la; ela vence em dez minutos. Se o estado na Meta mudou desde a proposta, pode ser necessário preparar outra.

As alterações de orçamento desse fluxo são limitadas a +50% ou -90% por proposta, usam a moeda da conta de anúncios e respeitam CBO na campanha/ABO no conjunto. Não permitem converter orçamento total em diário. O limite por proposta não é um teto acumulado diário nem um limite rígido para o gasto real da Meta.

Se o resultado estiver em verificação ou for incerto, não peça outra proposta para repetir a alteração. O Vyper precisa verificar primeiro o que aconteceu. Desabilitar propostas ou revogar o token impede aprovar suas propostas pendentes. Não há regras automáticas nem execuções programadas disponíveis por este MCP.

Revogar acesso e solucionar erros

Em MCP, confira validade, último uso e estado de cada token. Revogar interrompe novas consultas com essa credencial; removê-la do cliente não substitui revogá-la no Vyper. Se perdeu ou compartilhou o segredo, revogue-o e gere outro. A revogação não apaga as respostas que o cliente de IA já recebeu.

• Não autorizado / 401: confira token, validade, revogação e envio do cabeçalho correto pelo cliente.
• Propostas indisponíveis: revise a permissão específica do token e atualize as ferramentas. Não resolva compartilhando uma credencial mais ampla.
• Consultas demais / 429: aguarde e reduza chamadas repetidas; não gere tokens para contornar o limite.
• Período inválido ou relatório muito grande: use até 31 dias e restrinja oferta ou fonte.
• Dados parciais: revise a qualidade e atualize as fontes pelo Vyper. A IA não pode completar fatos ausentes por dedução.

O MCP não fornece telefones nem nomes de compradores, credenciais da Meta ou senhas de webhooks. Ele compartilha nomes operacionais e métricas agregadas da sua empresa com o cliente autorizado. Revise as configurações e condições de privacidade do cliente escolhido antes de conectá-lo.

Consulte como ler os relatórios e gerenciar campanhas e orçamentos.