Realize MCP - Taboola

Interaja com a plataforma de publicidade Taboola usando linguagem natural por meio da API Taboola Realize.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Servidor Realize MCP

Um servidor Model Context Protocol (MCP) que fornece acesso de leitura e escrita à API Realize da Taboola. Permite que assistentes de IA analisem campanhas, recuperem dados de desempenho, gerem relatórios e gerenciem campanhas e itens por meio de linguagem natural. Executa como um servidor HTTP Streamable com OAuth 2.1 — conecte-se ao servidor hospedado, sem necessidade de instalação local.

License MCP

Início Rápido

Conecte-se ao servidor Realize MCP hospedado usando transporte Streamable HTTP com OAuth 2.1. Multiusuário, sem estado, sem necessidade de instalação local.

Cada cliente abaixo conecta-se à mesma URL, https://mcp.realize.com/mcp, e autentica da mesma forma: no primeiro uso, abre um navegador para o SSO da Taboola, e o token de portador resultante é o que as ferramentas do Realize usam para executar.

Escolha a seção para o seu cliente:

Claude Desktop e claude.ai

O Realize está listado no diretório de conectores do Claude, então você pode adicioná-lo sem digitar uma URL.

Opção 1 — pelo diretório de conectores (recomendado):

  1. Vá para Configurações → Conectores e navegue pelos conectores disponíveis
  2. Encontre Realize e selecione Conectar
  3. Uma janela do navegador abrirá para o SSO da Taboola — insira suas credenciais para obter um token de portador usado pelas ferramentas do Realize

Opção 2 — como conector personalizado:

Use esta opção se precisar apontar o Claude para um endpoint MCP do Realize diferente.

  1. Vá para Configurações → Conectores → Adicionar Conector Personalizado
  2. Insira o nome do servidor MCP e a URL: https://mcp.realize.com/mcp
  3. Selecione Conectar para iniciar o fluxo OAuth 2.1
  4. Uma janela do navegador abrirá para o SSO da Taboola — insira suas credenciais para obter um token de portador usado pelas ferramentas do Realize

Claude Code (CLI)

claude mcp add --transport http realize-mcp https://mcp.realize.com/mcp

Em seguida, execute /mcp dentro do Claude Code para acionar o fluxo OAuth.

Codex

codex mcp add realize-mcp --url https://mcp.realize.com/mcp

O Codex detecta que o servidor requer OAuth e inicia o fluxo para você. Para reautenticar posteriormente, execute codex mcp login realize-mcp.

codex mcp add grava a entrada em ~/.codex/config.toml, então o Codex Desktop também a reconhece — reinicie-o após adicionar. Para gravar a entrada manualmente:

[mcp_servers.realize-mcp]
url = "https://mcp.realize.com/mcp"

Cursor

Adicione o servidor a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "realize-mcp": {
      "url": "https://mcp.realize.com/mcp"
    }
  }
}

Os agentes de nuvem/web do Cursor também são suportados — eles completam o mesmo fluxo OAuth através do callback hospedado do próprio Cursor, sem necessidade de registrar nada antecipadamente.

Outros clientes MCP

Qualquer cliente que fale Streamable HTTP pode conectar-se apenas com a URL do servidor:

{
  "mcpServers": {
    "realize-mcp": {
      "type": "http",
      "url": "https://mcp.realize.com/mcp"
    }
  }
}

Seu cliente registra-se automaticamente na primeira conexão, então não há nada para configurar antecipadamente — nenhum ID de cliente para solicitar à Taboola, nenhuma porta de callback para fixar e nenhum processo de ponte como mcp-remote. Qualquer callback que seu cliente use, uma porta local ou sua própria URL hospedada, é aceito como está.

Referência de Ferramentas

Gerenciamento de Contas

search_accounts — Pesquise contas por ID numérico ou consulta de texto. Chame esta primeiro para obter os valores de account_id necessários para todas as outras ferramentas. Os resultados incluem currency, country e time_zone_name para que o LLM possa escolher os valores corretos de orçamento e fuso horário.

query        (string, optional)            Digit-only = exact ID lookup; text = fuzzy name lookup; leave empty to list all accounts
page         (integer, default: 1)         min: 1
page_size    (integer, default: 10)        min: 1, max: 10 (hard cap)

Gerenciamento de Campanhas

Uma campanha contém orçamento, lances, agendamento e segmentação. Ela contém itens.

list_campaigns — Liste campanhas para uma conta (uma página por chamada).

account_id   (string, required)
page         (integer, default: 1)         min: 1
page_size    (integer, default: 10)        min: 1, max: 10 (hard cap)

get_campaign — Obtenha detalhes específicos de uma campanha.

account_id   (string, required)
campaign_id  (string, required)

get_campaign_reach_estimate — Estime o alcance para uma configuração hipotética de campanha antes do lançamento. Previsão baseada em segmentação + lance/orçamento opcionais, não em desempenho histórico. Retorna limites inferior/superior para impressões e/ou usuários únicos mensais.

account_id        (string, required)
campaign          (object, required)              Same targeting blocks as create_campaign / update_campaign below. Reach narrows as more inputs are added: targeting only → audience reach; + cpc (pricing_model=CPC) → narrowed by bid competitiveness; + spending_limit or daily_cap → additionally capped by impressions the budget can afford.
estimation_types  (array of string, optional)     IMPRESSIONS | MONTHLY_USERS — omit for both

Ferramentas de escrita de campanha (create_campaign, update_campaign)

Ambas as ferramentas aceitam os mesmos escalares e blocos de segmentação. Escalares fazem merge parcial; blocos de segmentação fazem substituição completa dentro do bloco. Novas campanhas são enviadas pausadas, a menos que is_active=true seja enviado.

Obrigatório difere:

create_campaign:  account_id, name, marketing_objective, branding_text, spending_limit_model, bid_strategy
update_campaign:  account_id, campaign_id

Escalares (todos opcionais na atualização; os obrigatórios na criação acima são obrigatórios na criação):

name                     (string)
marketing_objective      (string enum)        BRAND_AWARENESS | DRIVE_WEBSITE_TRAFFIC | LEADS_GENERATION | ONLINE_PURCHASES | MOBILE_APP_INSTALL
branding_text            (string)             Brand name shown with ads
spending_limit_model     (string enum)        NONE | MONTHLY | ENTIRE
spending_limit           (number)             Budget amount in account's default currency
daily_cap                (number)             Daily spend cap
pricing_model            (string enum)        CPC | VCPM   (default CPC; VCPM requires bid_strategy=FIXED)
bid_strategy             (string enum)        SMART | FIXED | TARGET_CPA | MAX_CONVERSIONS | MAX_VALUE
cpc                      (number)             Bid amount in account's default currency (per-click for CPC; per-1000-viewable-impressions for VCPM)
cpa_goal                 (number)             Target cost per acquisition (TARGET_CPA only)
cpc_cap                  (number)             Upper bound on bids
start_date               (string)             YYYY-MM-DD
end_date                 (string)             YYYY-MM-DD
tracking_code            (string)             Query string appended to item URLs
daily_ad_delivery_model  (string enum)        BALANCED | STRICT
traffic_allocation_mode  (string enum)        OPTIMIZED | EVEN
is_active                (boolean)            true to launch, false to pause

Blocos de segmentação (todos object, opcionais, substituição completa dentro do bloco):

country_targeting              Classic country (codes from search_geos dimension=countries)
region_country_targeting       Classic region (codes from search_geos dimension=regions)
dma_country_targeting          Classic DMA — US-only (codes from search_geos dimension=dma)
city_targeting                 Classic city (codes from search_geos dimension=cities)
postal_code_targeting          Classic postal code (codes from search_geos dimension=postal_codes)
platform_targeting             DESK | PHON | TBLT | TV | OTHR
os_targeting                   OS family + version (versions via search_techno)
browser_targeting              Browser names from search_techno dimension=browsers
connection_type_targeting      WIFI
activity_schedule              Dayparting (time_zone via list_time_zones)
conversion_rules               Conversion rule attachments (rules via get_conversion_rules)
publisher_targeting            Publisher allow/block-list (search_publishers)
publisher_bid_modifier         Per-publisher CPC bid modifier
contextual_segments_targeting  Contextual segments (search_contextual_segments)
audiences_targeting            First-party + custom audiences (search_audiences)
lookalike_audience_targeting   Lookalike audiences (search_lookalike_audiences)

Itens

Um item é uma peça criativa veiculada sob uma campanha. Dois tipos são suportados: nativo (URL rastreada ou título/imagem/URL manual) e display (tag de anúncio de terceiros ou ativo hospedado no Realize).

list_items — Liste itens para uma campanha.

account_id   (string, required)
campaign_id  (string, required)

get_item — Obtenha um item específico.

account_id   (string, required)
campaign_id  (string, required)
item_id      (string, required)

create_native_item — Crie um item nativo em uma campanha.

account_id     (string, required)
campaign_id    (string, required)
url            (string, required)            Landing URL
title          (string, required)            Headline
description    (string, required)            Body
thumbnail_url  (string, required)            Image URL
branding_text  (string)
creative_name  (string)                      Human-readable creative label shown in the Realize UI
cta            (object)                      {cta_type} — values from list_cta_types

update_native_item — Atualize campos específicos em um item nativo. Envie [] para verification_pixel / viewability_tag para limpar.

account_id          (string, required)
campaign_id         (string, required)
item_id             (string, required)
url                 (string)
title               (string)
description         (string)
thumbnail_url       (string)
branding_text       (string)
creative_name       (string)                 Human-readable creative label shown in the Realize UI
is_active           (boolean)                Pause/resume
cta                 (object)                 {cta_type}
verification_pixel  (object)                 Tracking pixels (full-replace within block)
viewability_tag     (object)                 Viewability tag (full-replace within block)

Editabilidade: itens em PENDING_APPROVAL aceitam edições completas; RUNNING / PAUSED aceitam apenas alternâncias de is_active mais metadados menores; itens REJECTED não podem ser editados (recrie).

create_display_item — Crie um item de display em uma campanha. Envie exatamente um de ad_tag (tag de terceiros) ou asset_url (ativo hospedado no Realize).

account_id     (string, required)
campaign_id    (string, required)
url            (string, required)            Landing URL
creative_name  (string, required)            Human-readable creative label shown in the Realize UI
ad_tag         (string)                      3P tag (raw HTML/JS). Pair with `dimensions`.
dimensions     (array of {width,height})     Required with `ad_tag`; rejected with `asset_url`.
asset_url      (string)                      1P hosted asset URL (image/video/HTML5 zip). Realize ingests by file extension.

update_display_item — Atualize campos em um item de display. Envie [] para verification_pixel / viewability_tag para limpar.

account_id          (string, required)
campaign_id         (string, required)
item_id             (string, required)
url                 (string)
creative_name       (string)
is_active           (boolean)                Pause/resume
ad_tag              (string)                 Swap 3P tag; requires `dimensions`.
dimensions          (array of {width,height})
asset_url           (string)                 Swap 1P hosted asset (re-ingest by file extension).
verification_pixel  (object)                 Tracking pixels (full-replace within block)
viewability_tag     (object)                 Viewability tag (full-replace within block)

Descoberta

Use estas ferramentas para preencher campos de segmentação de campanhas e itens com valores válidos.

search_geos — Países, regiões, DMAs, cidades, códigos postais. Retorna pares de {code, name}; use o campo code para segmentação.

dimension     (string enum, required)       countries | regions | dma | cities | postal_codes
country_code  (string)                      Required for regions / dma / cities / postal_codes

search_techno — Versões de SO e navegadores.

dimension  (string enum, required)          operating_system_versions | browsers
os_family  (string)                         Required for operating_system_versions

search_audiences — Audiências primárias e personalizadas para uma conta.

account_id              (string, required)
country_codes           (string)
country_targeting_type  (string enum)       ALL | INCLUDE | EXCLUDE

search_lookalike_audiences — Audiências semelhantes (lookalike) de CRM / pixel / PBP.

account_id    (string, required)
country_code  (string)

search_contextual_segments — Segmentos contextuais.

account_id              (string, required)
country_codes           (string)
country_targeting_type  (string enum)       ALL | INCLUDE | EXCLUDE

search_publishers — Editores que uma conta pode segmentar.

account_id     (string, required)
query          (string, required)
publisher_ids  (array)
page           (integer, default: 1)        min: 1
page_size      (integer, default: 10)       min: 1, max: 50

list_time_zones — Nomes de fusos horários IANA para activity_schedule.time_zone. Sem parâmetros.

list_cta_types — Valores de cta.cta_type para create_native_item / update_native_item. Sem parâmetros.

Regras de Conversão

Regras de conversão definem como o pixel universal atribui conversões para uma conta, e seus IDs preenchem conversion_rules na criação/atualização de campanha. Não há exclusão — retire uma regra definindo status para DISABLED / ARCHIVED.

get_conversion_rules — Liste as regras ACTION de uma conta (paginadas) ou busque uma por rule_id. Em uma conta NETWORK/pai, a listagem abrange contas filhas; o advertiser_id de cada regra nomeia seu proprietário.

account_id   (string, required)
rule_id      (string)                      Omit to list; set (numeric id as a string) to fetch one. Empty string is rejected
page         (integer, default: 1)         Ignored when rule_id is set
page_size    (integer, default: 25)        min: 1, max: 50. Ignored when rule_id is set
status       (string enum)                 ACTIVE | DISABLED | ARCHIVED (ARCHIVED also selects disabled rules)
search_text  (string)                      Case-insensitive substring match on display_name

create_conversion_rule — Crie uma regra de conversão. display_name é único por conta, e um evento pode conter apenas uma regra ACTIVE. Retorna a regra criada com seu id atribuído pelo servidor.

account_id                     (string, required)
display_name                   (string, required)       Unique per account
event_name                     (string, required)       'page_view' for BASIC; any custom event for EVENT_BASED
type                           (string enum, required)  BASIC | EVENT_BASED
category                       (string enum, required)  VIEW_CONTENT | SEARCH | ADD_TO_CART | ... | MAKE_PURCHASE | LEAD | ... | OTHER
condition                      (object, required)       Recursive match tree; leaf = property + predicate, branch = AND/OR/NOT + children[]
look_back_window               (integer, required)      Click-through attribution window in DAYS (1-30)
include_in_total_conversions   (boolean, required)      Count toward account Total Conversions
status                         (string enum, required)  ACTIVE | DISABLED | ARCHIVED
effects                        (array, required)        Revenue effects: [{type: REVENUE, data: "<numeric string>"}]; [] for none
view_through_look_back_window  (integer)                View-through window in MINUTES (1-10080)
include_in_total_value         (boolean)                Defaults to include_in_total_conversions
aggregation_type               (string enum)            AGGREGATED | LAST_VALUE (default AGGREGATED)
description                    (string)

update_conversion_rule — Atualize uma regra de conversão. Envie apenas os campos que está alterando; campos omitidos mantêm seu valor armazenado. Não ecoe de volta um objeto get_conversion_rules — seus nulos e campos somente leitura são rejeitados. type / category / event_name são imutáveis.

account_id  (string, required)
rule_id     (string, required)
...         Any writable field from create_conversion_rule (send only the ones you are changing)

Relatórios (Formato CSV)

As ferramentas de relatório retornam CSV: um banner de resumo (contagem de registros, granularidade de linha, paginação) seguido pelas próprias linhas. Existem duas superfícies de relatório:

  • Relatórios dinâmicos — get_dynamic_report_settings, depois get_dynamic_report_data. Você escolhe as dimensões, métricas, filtros e ordenação, então detalhamentos por campanha, site, dia e conteúdo e listas top-N são todos construídos aqui.
  • get_campaign_history_report — um log fixo de alterações/auditoria para campanhas.

Relatórios dinâmicos

get_dynamic_report_settings — Primeiro passo obrigatório. Retorna o metamodelo da conta: cada dimensão, métrica e filtro disponível, e os operadores que cada filtro aceita. get_dynamic_report_data rejeita nomes que não estão nele, então obtenha-os daqui em vez de adivinhar.

account_id   (string, required)              From search_accounts
report_type  (string, default: PERFORMANCE)  PERFORMANCE is currently the only supported value
name_filter  (string)                        Case-insensitive substring; narrows columns, filters and the conversion-rule list

get_dynamic_report_data — Execute uma consulta construída a partir desses nomes e retorne as linhas como CSV.

account_id   (string, required)              From search_accounts
columns      (array, required)               Fully qualified dimension/metric names from the metamodel
date_preset  (string enum)                   YESTERDAY | LAST_7_DAYS | LAST_14_DAYS | LAST_30_DAYS | LAST_90_DAYS |
                                             THIS_MONTH | LAST_MONTH | THIS_QUARTER | LAST_QUARTER | THIS_YEAR | LAST_12_MONTHS
date_from    (string)                        Custom range start, yyyy-MM-dd
date_to      (string)                        Custom range end, yyyy-MM-dd, on or after date_from
filters      (array)                         [{name, operator, values}] — EQUALS | NOT_EQUALS | IN | NOT_IN |
                                             GREATER_THAN | LESS_THAN | BETWEEN | LIKE. Account and date filters are added for you
sort         (array)                         [{column, direction}], applied in list order; each column must also appear in `columns`
page         (integer, default: 1)           min: 1
page_size    (integer, default: 20)          min: 1, max: 100
report_type  (string, default: PERFORMANCE)  PERFORMANCE is currently the only supported value

Passe ou date_preset ou date_from + date_to, nunca ambos; um intervalo personalizado pode abranger no máximo 12 meses. Para top N por uma métrica, ordene por ela DESC e defina page_size como N. Não há total geral — uma página cheia significa que mais linhas permanecem.

get_campaign_history_report

Um log de alterações/auditoria em vez de um relatório de desempenho: uma linha por evento de alteração (change_type, old_value → new_value, performer), sem métricas de impressão, clique, gasto ou taxa.

account_id  (string, required)            From search_accounts
start_date  (string, required)            Format: YYYY-MM-DD
end_date    (string, required)            Format: YYYY-MM-DD
page        (integer, default: 1)         min: 1
page_size   (integer, default: 20)        min: 1, max: 100

Granularidade e interpretação de dados

Os relatórios retornam linhas achatadas. Cada relatório tem uma granularidade de linha — a chave composta que torna uma linha única. O mesmo site_id pode aparecer sob várias campanhas, então as linhas devem ser lidas em sua granularidade, não mescladas por um único id.

get_dynamic_report_data       the dimension columns you requested   # metrics-only query = one aggregate row, no grain
get_campaign_history_report   (campaign_id, change_time, id)        # audit log, not metrics

Cada resposta nomeia sua granularidade explicitamente no banner — essa, não a ordem das colunas, é a chave autoritativa. Colunas de granularidade e chave não são garantidas de liderar ou serem adjacentes, e os nomes das colunas são os rótulos do metamodelo, então não confie na posição.

As métricas são calculadas no servidor. ctr, cpc, cpm, cpa, cvr, roas são pré-calculadas por linha — leia-as como estão. Não as recalcule ou faça média entre linhas. Para agregar volume, some apenas os contadores brutos (clicks, impressions, spent).

Entre contas: os relatórios são limitados ao único account_id consultado e não agregam contas filhas; consulte cada conta filha separadamente. IDs de campanha/site/item são globalmente únicos, então nenhuma coluna de conta é necessária na granularidade.

Regras para números corretos:

  • Onde o banner relata um Total, ele é autoritativo — não some linhas entre páginas para derivar totais ou taxas.

Exemplos de Uso

Uso Básico

User: "Show me campaigns for Marketing Corp"
AI:
  1. Searches accounts for "Marketing Corp"
  2. Retrieves campaigns using the found account_id
  3. Returns campaign list with performance metrics

Importante: Todas as operações exigem obter valores de account_id de search_accounts primeiro — nunca use IDs numéricos diretamente.

Encontrar Conta e Listar Campanhas

User: "Show campaigns for account 12345"
AI Process:
  Step 1: search_accounts("12345") → Returns account_id: "advertiser_12345_prod"
  Step 2: list_campaigns(account_id="advertiser_12345_prod")
  Result: List of campaigns with details

Obter Relatório de Desempenho

User: "Get campaign performance for Marketing Corp last month"
AI Process:
  Step 1: search_accounts("Marketing Corp") → account_id: "mktg_corp_001"
  Step 2: get_dynamic_report_settings(account_id="mktg_corp_001")
          → the exact column names to use, e.g. PERFORMANCE_REPORT.CAMPAIGN.CAMPAIGN_NAME,
            PERFORMANCE_REPORT.METRICS.CLICKS, PERFORMANCE_REPORT.METRICS.SPENT
  Step 3: get_dynamic_report_data(
    account_id="mktg_corp_001",
    columns=[
      "PERFORMANCE_REPORT.CAMPAIGN.CAMPAIGN_NAME",
      "PERFORMANCE_REPORT.METRICS.CLICKS",
      "PERFORMANCE_REPORT.METRICS.SPENT"
    ],
    date_preset="LAST_MONTH"
  )
  Result: CSV report with one row per campaign

Conteúdo de Melhor Desempenho

User: "Show top 20 performing content items"
AI Process:
  Step 1: search_accounts(...) → account_id: "mktg_corp_001"
  Step 2: get_dynamic_report_settings(account_id="mktg_corp_001", name_filter="item")
          → the item/content dimension and metric names available to this account
  Step 3: get_dynamic_report_data(
    account_id="mktg_corp_001",
    columns=["<item dimension>", "PERFORMANCE_REPORT.METRICS.SPENT"],
    date_preset="LAST_30_DAYS",
    sort=[{"column": "PERFORMANCE_REPORT.METRICS.SPENT", "direction": "DESC"}],
    page_size=20
  )
  Result: Top 20 content items by spend

Atualizar Orçamento de uma Campanha

User: "Bump the daily cap on Marketing Corp's Spring Sale campaign to $500"
AI Process:
  Step 1: search_accounts("Marketing Corp") → account_id: "mktg_corp_001"
  Step 2: list_campaigns(account_id="mktg_corp_001") → find Spring Sale → campaign_id: "12345678"
  Step 3: update_campaign(
    account_id="mktg_corp_001",
    campaign_id="12345678",
    daily_cap=500
  )
  Result: Campaign updated; other fields and targeting untouched

Estimar Alcance Antes do Lançamento

User: "How many people could we reach on desktop in the US for Marketing Corp?"
AI Process:
  Step 1: search_accounts("Marketing Corp") → account_id: "mktg_corp_001"
  Step 2: get_campaign_reach_estimate(
    account_id="mktg_corp_001",
    campaign={
      "country_targeting": {"type": "INCLUDE", "value": ["US"]},
      "platform_targeting": {"type": "INCLUDE", "value": ["DESK"]}
    },
    estimation_types=["IMPRESSIONS", "MONTHLY_USERS"]
  )
  Result: Lower/upper bound estimates for impressions and monthly unique users

Criar um Item Nativo

User: "Add a new ad to campaign 12345678 pointing at example.com/landing — headline 'Save 20% This Spring', body 'Limited-time offer on all spring collection items.', thumbnail https://cdn.example.com/spring.jpg, Shop Now CTA"
AI Process:
  Step 1: search_accounts(...) → account_id: "mktg_corp_001"
  Step 2: list_cta_types() → confirm "SHOP_NOW" is a valid cta_type
  Step 3: create_native_item(
    account_id="mktg_corp_001",
    campaign_id="12345678",
    url="https://example.com/landing",
    title="Save 20% This Spring",
    description="Limited-time offer on all spring collection items.",
    thumbnail_url="https://cdn.example.com/spring.jpg",
    cta={"cta_type": "SHOP_NOW"}
  )
  Result: Native item created

Recursos de Relatório

  • Formato CSV: Os relatórios retornam dados CSV eficientes com um banner de resumo (registros, granularidade de linha, paginação) acima das linhas
  • Paginação: page_size padrão=20, máximo=100 para evitar respostas sobrecarregadas
  • Ordenação: Relatórios dinâmicos ordenam por qualquer coluna solicitada, em qualquer direção; combine uma ordenação DESC com page_size=N para uma lista top-N
  • Otimização de Tamanho: Truncamento automático para grandes conjuntos de dados

Suporte

Para preocupações de produto ou segurança, relatórios de bugs e solicitações de recursos, abra uma issue em github.com/taboola/realize-mcp/issues.

Privacidade e Tratamento de Dados

O Realize MCP acessa a API Realize usando suas credenciais OAuth e retorna dados apenas ao seu cliente MCP conectado. As informações processadas em conexão com seu uso do Realize MCP são tratadas de acordo com a Política de Privacidade da Taboola.

Licença

Licenciado sob a Apache License 2.0. Consulte LICENSE para detalhes.

Servidor Realize MCP — Acesso seguro e eficiente à plataforma de publicidade da Taboola por meio de linguagem natural.