Pular para o conteúdo principal

MCP/API

MCP/API é a interface programática unificada para o Qubix. Clientes externos — um assistente de IA, um script de BI, uma ferramenta de automação — conectam-se a um único endpoint pelo protocolo MCP (Model Context Protocol) e chamam os métodos listados nesta página. Cada chamada é executada estritamente dentro das suas permissões: um administrador alcança toda a conta, um buyer apenas os dados da sua equipe.

Não há uma API REST separada para aprender: os métodos que você vê aqui são exatamente o que o endpoint serve, então o catálogo nunca pode divergir da interface real.

Os mesmos métodos alimentam o assistente integrado​

Estes métodos não são apenas para clientes externos. O assistente de IA integrado do Qubix — o painel disponível em cada tela do painel de administração, sem nenhuma configuração — chama exatamente o mesmo catálogo. Portanto, seja perguntando ao assistente integrado ou conectando o seu próprio agente de IA por MCP, ambos leem os seus dados e executam ações através dos mesmos métodos, sempre dentro das suas permissões.

Onde encontrar​

No painel de administração, abra o menu da conta (canto superior direito, ao lado do seu nome) e escolha MCP/API.

O endpoint​

Tudo vai para um único endereço:

POST https://<your-domain>/api/mcp

O transporte é Streamable HTTP (JSON-RPC 2.0) — um único endpoint que os clientes MCP prontos falam nativamente e que você também pode chamar diretamente de qualquer linguagem (veja Exemplos de código abaixo).

O seu token de API​

O acesso programático usa um token pessoal (PAT) — criado e gerenciado diretamente nesta página, no bloco API Token.

  1. Pressione Gerar API token (ou Regenerar, se você já tiver um).
  2. Copie o token imediatamente — ele é exibido apenas uma vez.

O token tem o formato qbx_…. O Qubix armazena apenas o hash dele e nunca poderá exibi-lo novamente.

  • Um token por usuário. Ele herda a sua função e permissões, então pela API você vê exatamente os mesmos dados e ações que na interface.
  • Regenerar emite um novo token e o antigo para de funcionar imediatamente.
  • Revogar exclui o token e corta todo o acesso que o utilizava.
Trate o token como uma senha

Um token pessoal equivale a entrar na conta como você. Não o publique nem o compartilhe. Se ele vazar, pressione Regenerar aqui — o token antigo morre na hora.

Conectar um cliente​

A maioria dos clientes MCP aceita uma pequena configuração: o endpoint mais o cabeçalho Authorization. Enquanto o token é exibido logo após a geração, esta página já preenche o valor real no exemplo abaixo — copie-o como está.

JSON
{
  "mcpServers": {
    "qubix": {
      "url": "https://<your-domain>/api/mcp",
      "headers": { "Authorization": "Bearer qbx_YOUR_TOKEN" }
    }
  }
}

Para a configuração passo a passo de um assistente específico (Claude Code, Claude Desktop, Cursor), veja Conectando uma AI externa.

Exemplos de código​

Para chamar o endpoint a partir do seu próprio código, envie uma requisição JSON-RPC com os cabeçalhos de autenticação e de Streamable HTTP. A página oferece snippets prontos para cURL, JavaScript e Python — troque a aba e copie. Por exemplo, listando os métodos disponíveis:

Bash
curl -X POST 'https://<your-domain>/api/mcp' \
  -H 'Authorization: Bearer qbx_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Python
import requests

res = requests.post(
    "https://<your-domain>/api/mcp",
    headers={
        "Authorization": "Bearer qbx_YOUR_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
    },
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list"},
)
print(res.text)
Para integrações próprias

Estas chamadas brutas ilustram o protocolo a partir de qualquer linguagem. Clientes prontos (Claude, Cursor) não precisam delas — eles usam a configuração acima.

O que a API expõe​

A página lista o catálogo de métodos completo — cerca de uma centena de métodos hoje — e cada um é marcado como leitura ou escrita. Eles cobrem, dentro das suas permissões:

  • Analytics — o dashboard, geo, ofertas, redes, fontes de tráfego, as telas do Facebook e o funil de visitantes, além de um drill-down para um único anúncio, campanha, oferta, criativo, PWA, geo ou fonte de tráfego.
  • Criativos — busca semântica e os temas de criativos com melhor desempenho.
  • Britva — visualizar regras de automação, anúncios pausados e o histórico de disparos; criar, editar e liberar regras.
  • Ações — pausar e retomar anúncios e campanhas; gerenciar ofertas, redes, fontes de tráfego, campanhas de tracker, pixels, sites, domínios, PWAs e campanhas de push.
  • Consultas livres — um método de consulta somente leitura para perguntas que os métodos prontos não cobrem.

Cada método mostra os seus parâmetros e se altera dados. Use a caixa de busca para encontrar um por nome ou descrição.

Os métodos de escrita são reais

Pausar um anúncio, excluir uma regra ou uma oferta pela API altera as suas campanhas ativas. Em clientes de chat, tais ações são executadas apenas após a sua confirmação — revise o que é proposto antes de aprovar.

O que vem a seguir​

Conectando uma AI externa

configure Claude, Cursor ou outro cliente MCP passo a passo.

Conexões

chaves para os serviços externos com que o Qubix se integra.

Modelos

quais dados e ações a sua função — e portanto o seu token — pode alcançar.

On this page