Realize MCP Server

A Model Context Protocol (MCP) server that provides read-only access to Taboola's Realize API, enabling AI assistants to analyze campaigns, retrieve performance data, and generate reports through natural language. Install the MCP Server with stdio transport for single-user local use, or Streamable HTTP transport for multi-user deployment.

---

Quick Start (Remote MCP)

Connect to the hosted Realize MCP server using Streamable HTTP transport with OAuth 2.1. Multi-user, stateless, no local install required.

Cursor IDE / Claude Desktop — Add to your MCP client config:

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

Claude Desktop (UI)

1. Go to Settings → Connectors → Add Custom Connector
2. Enter the MCP Server name and URL: https://mcp.realize.com/mcp
3. Select Connect to initiate the OAuth 2.1 flow
4. A browser window will open to Taboola SSO—enter your credentials to obtain a bearer token used by Realize tools

Claude Code (CLI)

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

---

Tools Reference

Account Management

search_accounts — Search accounts by numeric ID or text query. Call this first to get account_id values needed by all other tools.

query       (string, required)            Cannot be empty. Numeric = exact ID; text = fuzzy name
page        (integer, default: 1)         min: 1
page_size   (integer, default: 10)        min: 1, max: 10 (hard cap)

Campaign Management

All campaign tools require account_id (string from search_accounts), not a raw numeric ID. No pagination — all results returned in a single response.

get_all_campaigns — List all campaigns for an account.

account_id  (string, required)

get_campaign — Get specific campaign details.

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

get_campaign_items — Get all items/creatives for a campaign.

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

get_campaign_item — Get a specific campaign item's details.

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

Reporting (CSV Format)

All report tools return CSV with a summary header. Every report requires these parameters:

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

Some reports also support sorting and filtering:

sort_field      (string, optional)        Allowed: clicks, spent, impressions
sort_direction  (string, default: DESC)   Allowed: ASC, DESC
filters         (object, optional)        JSON object with string values only

get_top_campaign_content_report — Top performing campaign content. Supports: shared params + sort.

get_campaign_breakdown_report — Campaign performance breakdown. Supports: shared params + sort + filters.

get_campaign_history_report — Historical campaign data. Supports: shared params only (no sort, no filters).

get_campaign_site_day_breakdown_report — Site/day performance breakdown. Supports: shared params + sort + filters.

Authentication (stdio only)

These tools are only available in stdio mode, where the server manages its own client credentials. In Streamable HTTP mode, authentication is handled at the transport layer via OAuth 2.1 so these tools are excluded.

get_auth_token — Authenticate with Realize API using client credentials (REALIZE_CLIENT_ID/REALIZE_CLIENT_SECRET).

get_token_details — Get details about the current authentication token.

---

Usage Examples

Basic Usage

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

Important: All operations require getting account_id values from search_accounts first - never use numeric IDs directly.

Find Account and List Campaigns

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

Get Performance Report

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_campaign_breakdown_report(
    account_id="mktg_corp_001",
    start_date="2024-01-01",
    end_date="2024-01-31"
  )
  Result: CSV report with campaign metrics

Top Performing Content

User: "Show top 20 performing content items"
AI Process:
  get_top_campaign_content_report(
    account_id="account_id_from_search",
    start_date="2024-01-01",
    end_date="2024-01-31",
    page_size=20,
    sort_field="spent",
    sort_direction="DESC"
  )
  Result: Top content sorted by spend

Report Features

• CSV Format: Reports return efficient CSV data with headers and pagination info
• Pagination: Default page_size=20, max=100 to prevent overwhelming responses
• Sorting: Available for most reports by clicks, spent, or impressions
• Size Optimization: Automatic truncation for large datasets

---

Prometheus Metrics

Enabled by default (METRICS_ENABLED=true). Served on a dedicated port (default 8092, configurable via METRICS_PORT) in Streamable HTTP mode.

Metric	Type	Labels
realize_mcp_http_requests_total	Counter	method, endpoint, http_status
realize_mcp_http_request_latency_seconds	Histogram	endpoint
realize_mcp_tool_calls_total	Counter	tool_name, status
realize_mcp_tool_call_latency_seconds	Histogram	tool_name
realize_mcp_client_connections_total	Counter	client_name, client_version
realize_mcp_api_requests_total	Counter	method, endpoint_pattern, http_status
realize_mcp_api_request_latency_seconds	Histogram	method, endpoint_pattern
realize_mcp_api_errors_total	Counter	method, endpoint_pattern, error_type

---

Local Setup

Run the MCP server locally if you prefer to manage your own credentials or host the server yourself.

Prerequisites

• Python 3.10+ (Python 3.11+ recommended)
• MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.)

Option A: Stdio Transport (single-user, local)

Standard MCP transport for local clients. The server runs on your machine and uses server-side credentials for Taboola API authentication.

Prerequisites: Taboola Realize API credentials (REALIZE_CLIENT_ID and REALIZE_CLIENT_SECRET)

Install:

pip install realize-mcp

Cursor IDE - Add to Settings → Tools & MCP:

{
  "mcpServers": {
    "realize-mcp": {
      "command": "realize-mcp-server",
      "env": {
        "REALIZE_CLIENT_ID": "your_client_id",
        "REALIZE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Claude Desktop - Add to claude_desktop_config.json:

{
  "mcpServers": {
    "realize-mcp": {
      "command": "realize-mcp-server",
      "env": {
        "REALIZE_CLIENT_ID": "your_client_id",
        "REALIZE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add realize-mcp --transport stdio -e REALIZE_CLIENT_ID=your_client_id -e REALIZE_CLIENT_SECRET=your_client_secret -- realize-mcp-server

Option B: Self-Hosted Streamable HTTP

Run the Streamable HTTP transport yourself (multi-user via OAuth 2.1, stateless, k8s-friendly).

Prerequisites:

• OAuth Dynamic Client Registration client ID (OAUTH_DCR_CLIENT_ID)
• Optional: OAUTH_SERVER_URL (defaults to https://authentication.taboola.com/authentication)
• Publicly accessible server URL for OAuth callbacks
• MCP_SERVER_SCHEME — defaults to https. Set to http for local dev without TLS.

Install:

pip install realize-mcp

Start the server:

MCP_TRANSPORT=streamable-http OAUTH_DCR_CLIENT_ID=your_dcr_client_id realize-mcp-server

Client config (point to your self-hosted URL):

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

Endpoints:

• GET /.well-known/oauth-protected-resource - RFC 9728 Protected Resource Metadata (supports path-based discovery)
• GET /.well-known/oauth-authorization-server - RFC 8414 metadata (registration_endpoint rewritten)
• POST /register - RFC 7591 Dynamic Client Registration
• POST|GET|DELETE /mcp - MCP Streamable HTTP endpoint (requires Bearer token)
• GET /health - Health check endpoint for Kubernetes probes
• GET / on port 8092 - Prometheus metrics endpoint (separate port)

Troubleshooting

Test the server manually:

REALIZE_CLIENT_ID=test REALIZE_CLIENT_SECRET=test realize-mcp-server

You should see: INFO:realize.realize_server:Starting Realize MCP Server...

---

Detailed Documentation

For comprehensive information, see design.md:

• Recent Fixes & Version History - Detailed release notes and upgrade instructions
• Installation Options - PyPI & Source installation with troubleshooting
• Architecture & Design Principles - Technical implementation details
• Advanced Features - CSV format, pagination, sorting, and optimization
• Development Guide & Testing - Setup, testing, and contribution guidelines
• Comprehensive Troubleshooting - Detailed solutions for common issues
• Security Best Practices - Credential management and operational security
• Complete API Reference - Full technical API documentation
• Technology Stack Details - Dependencies and system requirements

---

License

Licensed under the Apache License 2.0. See LICENSE for details.

---

Realize MCP Server - Safe, efficient, access to Taboola's advertising platform through natural language.