Realize MCP - Taboola

Interactúa con la plataforma publicitaria de Taboola usando lenguaje natural a través de la API de Taboola Realize.

Documentación

Servidor Realize MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso de lectura y escritura a la API Realize de Taboola. Permite a los asistentes de IA analizar campañas, recuperar datos de rendimiento, generar informes y gestionar campañas y elementos mediante lenguaje natural. Se ejecuta como un servidor HTTP Streamable con OAuth 2.1: conéctese al servidor alojado, sin necesidad de instalación local.

License MCP


Inicio Rápido

Conéctese al servidor Realize MCP alojado utilizando el transporte HTTP Streamable con OAuth 2.1. Multiusuario, sin estado, sin necesidad de instalación local.

Cada cliente a continuación se conecta a la misma URL, https://mcp.realize.com/mcp, y se autentica de la misma manera: en el primer uso abre un navegador hacia el SSO de Taboola, y el token de portador resultante es con el que se ejecutan las herramientas de Realize.

Elija la sección correspondiente a su cliente:

Claude Desktop y claude.ai

Realize está listado en el directorio de conectores de Claude, por lo que puede agregarlo sin escribir una URL.

Opción 1 — desde el directorio de conectores (recomendado):

  1. Vaya a Configuración → Conectores y explore los conectores disponibles
  2. Encuentre Realize y seleccione Conectar
  3. Se abrirá una ventana del navegador hacia el SSO de Taboola: ingrese sus credenciales para obtener un token de portador utilizado por las herramientas de Realize

Opción 2 — como conector personalizado:

Utilice esta opción si necesita apuntar Claude a un endpoint diferente de Realize MCP.

  1. Vaya a Configuración → Conectores → Agregar Conector Personalizado
  2. Ingrese el nombre del servidor MCP y la URL: https://mcp.realize.com/mcp
  3. Seleccione Conectar para iniciar el flujo OAuth 2.1
  4. Se abrirá una ventana del navegador hacia el SSO de Taboola: ingrese sus credenciales para obtener un token de portador utilizado por las herramientas de Realize

Claude Code (CLI)

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

Luego ejecute /mcp dentro de Claude Code para activar el flujo OAuth.

Codex

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

Codex detecta que el servidor requiere OAuth e inicia el flujo por usted. Para reautenticarse más tarde, ejecute codex mcp login realize-mcp.

codex mcp add escribe la entrada en ~/.codex/config.toml, por lo que Codex Desktop también la detecta — reinícielo después de agregarla. Para escribir la entrada manualmente en su lugar:

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

Cursor

Agregue el servidor a ~/.cursor/mcp.json:

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

Los agentes de nube/web de Cursor también son compatibles: completan el mismo flujo OAuth a través del callback alojado de Cursor, sin necesidad de registrar nada de antemano.

Otros clientes MCP

Cualquier cliente que hable HTTP Streamable puede conectarse solo con la URL del servidor:

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

Su cliente se registra automáticamente en la primera conexión, por lo que no hay nada que configurar de antemano: no hay ID de cliente que solicitar a Taboola, ni puerto de callback que fijar, ni proceso puente como mcp-remote. Cualquier callback que use su cliente, un puerto local o su propia URL alojada, se acepta tal cual.


Referencia de Herramientas

Gestión de Cuentas

search_accounts — Busca cuentas por ID numérico o consulta de texto. Llámele primero para obtener los valores de account_id necesarios para todas las demás herramientas. Los resultados incluyen currency, country y time_zone_name para que el LLM pueda elegir los montos de presupuesto y la zona horaria correctos.

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)

Gestión de Campañas

Una campaña contiene presupuesto, oferta, programación y segmentación. Contiene elementos.

list_campaigns — Lista las campañas de una cuenta (una página por llamada).

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

get_campaign — Obtiene detalles específicos de una campaña.

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

get_campaign_reach_estimate — Estima el alcance para una configuración hipotética de campaña antes del lanzamiento. Pronóstico basado en segmentación + oferta/presupuesto opcional, no en rendimiento histórico. Devuelve límites inferior/superior para impresiones y/o usuarios únicos mensuales.

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

Herramientas de escritura de campañas (create_campaign, update_campaign)

Ambas herramientas aceptan los mismos escalares y bloques de segmentación. Los escalares se fusionan parcialmente; los bloques de segmentación se reemplazan por completo dentro del bloque. Las campañas nuevas se envían en pausa a menos que se envíe is_active=true.

Los requisitos difieren:

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

Escalares (todos opcionales en actualización; los obligatorios en creación anteriores son obligatorios al crear):

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

Bloques de segmentación (todos object, opcionales, reemplazo completo dentro del bloque):

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)

Elementos

Un elemento es un creativo servido bajo una campaña. Se admiten dos tipos: nativo (rastreado por URL o titular/imagen/URL manual) y display (etiqueta de anuncio 3P o activo alojado en Realize 1P).

list_items — Lista los elementos de una campaña.

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

get_item — Obtiene un elemento específico.

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

create_native_item — Crea un elemento nativo en una campaña.

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 — Actualiza campos específicos en un elemento nativo. Envíe [] para verification_pixel / viewability_tag para borrar.

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)

Editabilidad: los elementos en PENDING_APPROVAL aceptan ediciones completas; RUNNING / PAUSED aceptan solo alternancias de is_active más metadatos menores; los elementos REJECTED no se pueden editar (recrear).

create_display_item — Crea un elemento display en una campaña. Envíe exactamente uno de ad_tag (etiqueta de terceros 3P) o asset_url (activo alojado en Realize 1P).

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 — Actualiza campos en un elemento display. Envíe [] para verification_pixel / viewability_tag para borrar.

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)

Descubrimiento

Utilice estas herramientas para completar los campos de segmentación de campañas y elementos con valores válidos.

search_geos — Países, regiones, DMAs, ciudades, códigos postales. Devuelve pares de {code, name}; use el campo code para la segmentación.

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

search_techno — Versiones de SO y navegadores.

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

search_audiences — Audiencias de primera parte y personalizadas para una cuenta.

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

search_lookalike_audiences — Audiencias similares de CRM / píxel / PBP.

account_id    (string, required)
country_code  (string)

search_contextual_segments — Segmentos contextuales.

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

search_publishers — Editores a los que una cuenta puede 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 — Nombres de zonas horarias IANA para activity_schedule.time_zone. Sin parámetros.

list_cta_types — Valores de cta.cta_type para create_native_item / update_native_item. Sin parámetros.

Reglas de Conversión

Las reglas de conversión definen cómo el píxel universal atribuye conversiones para una cuenta, y sus IDs completan conversion_rules al crear/actualizar campañas. No hay eliminación: retire una regla estableciendo status a DISABLED / ARCHIVED.

get_conversion_rules — Lista las reglas ACTION de una cuenta (paginadas), o recupera una por rule_id. En una cuenta NETWORK/padre, el listado abarca las cuentas hijas; el advertiser_id de cada regla nombra a su propietario.

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 — Crea una regla de conversión. display_name es único por cuenta, y un evento puede tener solo una regla ACTIVE. Devuelve la regla creada con su id asignado por el 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 — Actualiza una regla de conversión. Envíe solo los campos que está cambiando; los campos omitidos conservan su valor almacenado. No repita un objeto get_conversion_rules — sus nulos y campos de solo lectura son rechazados. type / category / event_name son inmutables.

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

Informes (Formato CSV)

Las herramientas de informes devuelven CSV: un banner de resumen (recuento de registros, granularidad de filas, paginación) seguido de las filas. Hay dos superficies de informes:

  • Informes dinámicos — get_dynamic_report_settings, luego get_dynamic_report_data. Usted elige las dimensiones, métricas, filtros y orden, por lo que los desgloses por campaña, sitio, día y contenido, y las listas top-N se construyen aquí.
  • get_campaign_history_report — un registro fijo de cambios/auditoría para campañas.

Informes dinámicos

get_dynamic_report_settings — Primer paso obligatorio. Devuelve el metamodelo de la cuenta: cada dimensión, métrica y filtro disponible, y los operadores que acepta cada filtro. get_dynamic_report_data rechaza nombres que no estén en él, así que tómelos de aquí en lugar de adivinar.

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 — Ejecuta una consulta construida a partir de esos nombres y devuelve las filas 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

Pase o bien date_preset o bien date_from + date_to, nunca ambos; un rango personalizado puede abarcar como máximo 12 meses. Para top N por una métrica, ordene por ella DESC y establezca page_size a N. No hay total general: una página completa significa que quedan más filas.

get_campaign_history_report

Un registro de cambios/auditoría más que un informe de rendimiento: una fila por evento de cambio (change_type, old_value → new_value, performer), sin métricas de impresiones, clics, gasto o tasas.

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

Granularidad de datos e interpretación

Los informes devuelven filas aplanadas. Cada informe tiene una granularidad de fila — la clave compuesta que hace única una fila. El mismo site_id puede aparecer bajo varias campañas, por lo que las filas deben leerse en su granularidad, no fusionarse por un solo 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 respuesta nombra su granularidad explícitamente en el banner — esa, no el orden de columnas, es la clave autoritativa. Las columnas de granularidad y clave no están garantizadas a estar al inicio o ser adyacentes, y los nombres de columna son las etiquetas del metamodelo, así que no confíe en la posición.

Las métricas se calculan en el servidor. ctr, cpc, cpm, cpa, cvr, roas están precalculadas por fila — léalas tal cual. No las recalcule ni las promedie entre filas. Para agregar volumen, sume solo los contadores brutos (clicks, impressions, spent).

Entre cuentas: los informes están limitados al único account_id consultado y no acumulan cuentas hijas; consulte cada cuenta hija por separado. Los ids de campaña/sitio/elemento son globalmente únicos, por lo que no se necesita columna de cuenta en la granularidad.

Reglas para números correctos:

  • Donde el banner informe un Total, es autoritativo — no sume filas entre páginas para derivar totales o tasas.

Ejemplos 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 las operaciones requieren obtener los valores de account_id de search_accounts primero — nunca use IDs numéricos directamente.

Encontrar Cuenta y Listar Campañas

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

Obtener Informe de Rendimiento

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

Contenido de Mayor Rendimiento

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

Actualizar Presupuesto de Campaña

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 del Lanzamiento

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

Crear un Elemento 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

Características de Informes

  • Formato CSV: Los informes devuelven datos CSV eficientes con un banner de resumen (registros, granularidad de filas, paginación) sobre las filas
  • Paginación: page_size predeterminado=20, máximo=100 para evitar respuestas abrumadoras
  • Ordenamiento: Los informes dinámicos ordenan por cualquier columna solicitada, en cualquier dirección; combine un orden DESC con page_size=N para una lista top-N
  • Optimización de Tamaño: Truncamiento automático para conjuntos de datos grandes

Soporte

Para inquietudes de producto o seguridad, informes de errores y solicitudes de funciones, abra un issue en github.com/taboola/realize-mcp/issues.


Privacidad y Manejo de Datos

Realize MCP accede a la API de Realize usando sus credenciales OAuth y devuelve datos solo a su cliente MCP conectado. La información procesada en relación con su uso de Realize MCP se maneja de acuerdo con la Política de Privacidad de Taboola.


Licencia

Licenciado bajo la Licencia Apache 2.0. Consulte LICENCIA para más detalles.


Servidor Realize MCP — Acceso seguro y eficiente a la plataforma publicitaria de Taboola mediante lenguaje natural.