Realize MCP Server

https://github.com/taboola/realize-mcp
Admin
Realize MCP Server is a Model Context Protocol (MCP) server providing read-only access to Taboola's...
Tokens:18,856
Snippets:117
Trust Score:8.1
License:Apache-2.0
Update:7 months ago
Show doc for...
Tokens:
Raw
### Manage Project Dependencies and Development Environment

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Commands to install project dependencies, perform editable installs for development, and verify the environment setup.

```bash
pip install -r requirements.txt
pip install -e .
pip3 show realize-mcp
```

--------------------------------

### Install Realize MCP Server

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Installs the Realize MCP server package using pip. This is a prerequisite for both stdio and HTTP transport modes.

```bash
pip install realize-mcp
```

--------------------------------

### Start Realize MCP Server with Streamable HTTP Transport

Source: https://context7.com/taboola/realize-mcp/llms.txt

Starts the Realize MCP server with Streamable HTTP transport for multi-user production environments, utilizing OAuth 2.1 authentication. Optional environment variables can be set for port, scheme, authentication server URL, and log level.

```bash
# Start the server with Streamable HTTP transport
MCP_TRANSPORT=streamable-http OAUTH_DCR_CLIENT_ID=your_dcr_client_id realize-mcp-server

# Optional environment variables
# MCP_SERVER_PORT=8000 (default)
# MCP_SERVER_SCHEME=https (use "http" for local development)
# OAUTH_SERVER_URL=https://authentication.taboola.com/authentication
# LOG_LEVEL=DEBUG
```

--------------------------------

### Complete Workflow Example

Source: https://context7.com/taboola/realize-mcp/llms.txt

Demonstrates a complete workflow from searching for an account to generating a report, illustrating the required sequence of tool calls.

```APIDOC
## Complete Workflow Example

### Description
Demonstrates a complete workflow from searching for an account to generating a report, illustrating the required sequence of tool calls.

### Steps

1.  **Search for Account**: Find the `account_id` for a given organization.
    ```python
    # User: "Show me the top performing content for Marketing Corp in January 2024"
    search_accounts_call = {
        "name": "search_accounts",
        "arguments": {"query": "Marketing Corp"}
    }
    # Expected Response includes: account_id: "mktg_corp_001"
    ```

2.  **Retrieve Campaigns (Optional)**: Get a list of campaigns for the account to provide context.
    ```python
    get_campaigns_call = {
        "name": "get_all_campaigns",
        "arguments": {"account_id": "mktg_corp_001"}
    }
    # Expected Response: List of campaigns with IDs and names
    ```

3.  **Generate Campaign History Report**: Use the `account_id` and desired date range to get the campaign history.
    ```python
    get_campaign_history_report_call = {
        "name": "get_campaign_history_report",
        "arguments": {
            "account_id": "mktg_corp_001",
            "start_date": "2024-01-01",
            "end_date": "2024-01-31",
            "page": 1,
            "page_size": 100
        }
    }
    # Expected Response: CSV report data for January 2024
    ```
```

--------------------------------

### GET /metrics

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Exposes Prometheus-formatted metrics for monitoring the health and performance of the Realize MCP server.

```APIDOC
## GET /metrics

### Description
Retrieves the current state of system metrics in Prometheus format. This endpoint is enabled by default when `METRICS_ENABLED` is set to true.

### Method
GET

### Endpoint
/metrics

### Parameters
None

### Response
#### Success Response (200)
- **realize_mcp_http_requests_total** (Counter) - Total count of HTTP requests with labels: method, endpoint, http_status
- **realize_mcp_http_request_latency_seconds** (Histogram) - Latency of HTTP requests with label: endpoint
- **realize_mcp_tool_calls_total** (Counter) - Total count of tool calls with labels: tool_name, status
- **realize_mcp_tool_call_latency_seconds** (Histogram) - Latency of tool calls with label: tool_name
- **realize_mcp_client_connections_total** (Counter) - Total client connections with labels: client_name, client_version
- **realize_mcp_api_requests_total** (Counter) - Total API requests with labels: method, endpoint_pattern, http_status
- **realize_mcp_api_request_latency_seconds** (Histogram) - API request latency with labels: method, endpoint_pattern
- **realize_mcp_api_errors_total** (Counter) - Total API errors with labels: method, endpoint_pattern, error_type

#### Response Example
# HELP realize_mcp_http_requests_total Total HTTP requests
# TYPE realize_mcp_http_requests_total counter
realize_mcp_http_requests_total{method="GET",endpoint="/metrics",http_status="200"} 1
```

--------------------------------

### Start Realize MCP Server via CLI

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

This command initiates the Realize MCP server process using environment variables for client authentication. It is used for manual verification of the server startup sequence.

```bash
REALIZE_CLIENT_ID=test REALIZE_CLIENT_SECRET=test realize-mcp-server
```

--------------------------------

### GET /get_campaign

Source: https://context7.com/taboola/realize-mcp/llms.txt

Retrieves detailed information about a specific campaign, including status, budget, targeting, and performance metrics.

```APIDOC
## GET /get_campaign

### Description
Retrieves detailed information about a specific campaign, including status, budget, targeting, and performance metrics.

### Method
GET

### Endpoint
/get_campaign

### Parameters
#### Request Body
- **account_id** (string) - Required - The unique identifier for the advertiser account.
- **campaign_id** (string) - Required - The unique identifier for the campaign.

### Request Example
{
  "name": "get_campaign",
  "arguments": {
    "account_id": "advertiser_12345_prod",
    "campaign_id": "campaign_001"
  }
}

### Response
#### Success Response (200)
- **id** (string) - Campaign ID
- **name** (string) - Campaign Name
- **status** (string) - Campaign status
- **performance** (object) - Performance metrics

#### Response Example
{
  "id": "campaign_001",
  "name": "Summer Sale 2024",
  "status": "RUNNING",
  "performance": {
    "impressions": 125000,
    "clicks": 3750
  }
}
```

--------------------------------

### Pagination & Sorting - Get Campaign Breakdown Report

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

How to efficiently retrieve large datasets using pagination and sorting parameters for campaign reports.

```APIDOC
## Pagination & Sorting - Get Campaign Breakdown Report

### Description
This section details how to use pagination and sorting parameters to efficiently retrieve large datasets, specifically for campaign reports. It outlines available sort fields, directions, and their behavior.

### Method
Function Call / API Request

### Endpoint
`get_campaign_breakdown_report` (and other reporting tools)

### Parameters
#### Query Parameters
- **account_id** (string) - Required - The ID of the account.
- **start_date** (string) - Required - The start date for the report period (YYYY-MM-DD).
- **end_date** (string) - Required - The end date for the report period (YYYY-MM-DD).
- **page** (integer) - Optional - The page number to retrieve (default is 1).
- **page_size** (integer) - Optional - The number of records per page (default is 20, max is 100).
- **sort_field** (string) - Optional - The field to sort by (e.g., `clicks`, `spent`, `impressions`).
- **sort_direction** (string) - Optional - The direction of sorting (`ASC` or `DESC`, default is `DESC`).

### Request Example
```bash
get_campaign_breakdown_report(
  account_id="account_id",
  start_date="2024-01-01",
  end_date="2024-01-31", 
  page=1,
  page_size=100,
  sort_field="spent", 
  sort_direction="DESC"
)
```

### Response
#### Success Response (200)
- **Report Data** (CSV or JSON, depending on tool type) - Paginated and sorted report data.

#### Response Example
(CSV example for Campaign Breakdown Report)
```csv
campaign_id,campaign_name,impressions,clicks,ctr,spent,cpc,conversions
123456,"Summer Sale 2024",15000,750,0.05,125.50,0.167,25
...
```

#### Available Sort Fields
- `clicks`: Number of clicks received
- `spent`: Amount spent
- `impressions`: Number of impressions served

#### Sort Directions
- `ASC`: Ascending
- `DESC`: Descending (default)

#### Sort Behavior
- If `sort_field` is specified, data is sorted by that field and direction.
- If `sort_field` is not specified, data is returned in API default order.
- Default direction is `DESC`.
- Works seamlessly with pagination.

#### Natural Language Processing Examples
- "highest spend first" → `sort_field="spent", sort_direction="DESC"`
- "most clicks first" → `sort_field="clicks", sort_direction="DESC"`
- "lowest spend first" → `sort_field="spent", sort_direction="ASC"`
```

--------------------------------

### Realize MCP Server - Stdio Transport

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Provides setup instructions for the Realize MCP Server using stdio transport for local, single-user deployments. This method uses server-side credentials for authentication.

```APIDOC
## Realize MCP Server - Stdio Transport

### Description
This section covers the installation and client setup for the Realize MCP Server when using the standard stdio transport. This is suitable for local, single-user environments where the server manages its own Taboola API authentication via environment variables.

### Installation

```bash
pip install realize-mcp
```

### Client Setup Examples

**Cursor IDE:**
```json
{
  "mcpServers": {
    "realize-mcp": {
      "command": "realize-mcp-server",
      "env": {
        "REALIZE_CLIENT_ID": "your_client_id",
        "REALIZE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

**Claude Desktop:**
```json
{
  "mcpServers": {
    "realize-mcp": {
      "command": "realize-mcp-server",
      "env": {
        "REALIZE_CLIENT_ID": "your_client_id",
        "REALIZE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

**Claude Code (CLI):**

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

### Tools Reference (Stdio Only)

**`get_auth_token`**

*   **Description:** Authenticates with the Realize API using client credentials.
*   **Parameters:** None (uses environment variables `REALIZE_CLIENT_ID` and `REALIZE_CLIENT_SECRET`).

**`get_token_details`**

*   **Description:** Retrieves details about the current authentication token.
*   **Parameters:** None.

**`search_accounts`**

*   **Description:** Searches for accounts by numeric ID or text query. This should be called first to obtain `account_id` values.
*   **Parameters:**
    *   `query` (string, required) - Cannot be empty. Numeric for exact ID, text for fuzzy name.
    *   `page` (integer, optional, default: 1) - Minimum value: 1.
    *   `page_size` (integer, optional, default: 10) - Minimum value: 1, Maximum value: 10 (hard cap).
```

--------------------------------

### Example Campaign Breakdown Report CSV Format

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

An example of the enhanced CSV response format for campaign breakdown reports. This format is optimized for size and performance, featuring clear headers and data rows.

```csv
🏆 **Campaign Breakdown Report CSV** - Account: ABC123 | Period: 2024-01-01 to 2024-01-31
📊 Records: 250 | Total: 1500 | Page: 1 | Size: 250 | ⚠️ More data available

campaign_id,campaign_name,impressions,clicks,ctr,spent,cpc,conversions
123456,"Summer Sale 2024",15000,750,0.05,125.50,0.167,25
234567,"Winter Promo",8500,420,0.049,85.75,0.204,18
```

--------------------------------

### Get All Campaign Items

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Retrieves all items or creatives associated with a specific campaign. Requires `account_id` and `campaign_id` as strings. Results are returned in a single response.

```python
def get_campaign_items(account_id: str, campaign_id: str):
    """Get all items/creatives for a campaign.

    Args:
        account_id: The unique identifier for the account (string).
        campaign_id: The unique identifier for the campaign (string).

    Returns:
        A list of campaign item objects.
    """
    # Implementation details would go here
    pass
```

--------------------------------

### GET /get_campaign_items

Source: https://context7.com/taboola/realize-mcp/llms.txt

Retrieves all creative items (ads) associated with a specific campaign including thumbnails, headlines, and individual performance metrics.

```APIDOC
## GET /get_campaign_items

### Description
Retrieve all creative items (ads) associated with a specific campaign including thumbnails, headlines, and individual performance metrics.

### Method
GET

### Endpoint
/get_campaign_items

### Parameters
#### Request Body
- **account_id** (string) - Required - The unique identifier for the advertiser account.
- **campaign_id** (string) - Required - The unique identifier for the campaign.

### Request Example
{
  "name": "get_campaign_items",
  "arguments": {
    "account_id": "advertiser_12345_prod",
    "campaign_id": "campaign_001"
  }
}

### Response
#### Success Response (200)
- **results** (array) - List of creative items

#### Response Example
{
  "results": [
    {
      "id": "item_001",
      "title": "50% Off Summer Collection",
      "impressions": 45000
    }
  ]
}
```

--------------------------------

### GET /get_top_campaign_content_report

Source: https://context7.com/taboola/realize-mcp/llms.txt

Generates a CSV report of top-performing campaign content sorted by specified metrics with pagination support.

```APIDOC
## GET /get_top_campaign_content_report

### Description
Generate a CSV report of top-performing campaign content sorted by specified metrics. Supports pagination (max 100 records per page) and sorting by clicks, spent, or impressions.

### Method
GET

### Endpoint
/get_top_campaign_content_report

### Parameters
#### Request Body
- **account_id** (string) - Required
- **start_date** (string) - Required
- **end_date** (string) - Required
- **page** (integer) - Optional
- **page_size** (integer) - Optional
- **sort_field** (string) - Optional

### Request Example
{
  "name": "get_top_campaign_content_report",
  "arguments": {
    "account_id": "advertiser_12345_prod",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }
}

### Response
#### Success Response (200)
- **CSV Data** (string) - Returns a formatted CSV report string.
```

--------------------------------

### Get Specific Campaign Details

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Fetches detailed information for a specific campaign. Requires both `account_id` and `campaign_id` as strings. This operation does not involve pagination.

```python
def get_campaign(account_id: str, campaign_id: str):
    """Get specific campaign details.

    Args:
        account_id: The unique identifier for the account (string).
        campaign_id: The unique identifier for the campaign (string).

    Returns:
        A campaign details object.
    """
    # Implementation details would go here
    pass
```

--------------------------------

### Get All Campaigns

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Retrieves a list of all campaigns associated with a given account ID. Requires a valid `account_id` string. Returns all results in a single response without pagination.

```python
def get_all_campaigns(account_id: str):
    """List all campaigns for an account.

    Args:
        account_id: The unique identifier for the account (string).

    Returns:
        A list of campaign objects.
    """
    # Implementation details would go here
    pass
```

--------------------------------

### Python Function for Fetching Campaign Reports with Pagination and Sorting

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Example Python function demonstrating how to fetch campaign breakdown reports with support for pagination and sorting. This function allows specifying account ID, date range, page number, page size, sort field, and sort direction.

```python
# Get large datasets efficiently
get_campaign_breakdown_report(
  account_id="account_id",
  start_date="2024-01-01",
  end_date="2024-01-31", 
  page=1,
  page_size=100,
  sort_field="spent", 
  sort_direction="DESC"
)
```

--------------------------------

### Get Specific Campaign Item Details

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Fetches the details for a particular campaign item or creative. Requires `account_id`, `campaign_id`, and `item_id` as strings. No pagination is applied.

```python
def get_campaign_item(account_id: str, campaign_id: str, item_id: str):
    """Get a specific campaign item's details.

    Args:
        account_id: The unique identifier for the account (string).
        campaign_id: The unique identifier for the campaign (string).
        item_id: The unique identifier for the campaign item (string).

    Returns:
        A campaign item details object.
    """
    # Implementation details would go here
    pass
```

--------------------------------

### GET /get_campaign_site_day_breakdown_report

Source: https://context7.com/taboola/realize-mcp/llms.txt

Generates a detailed CSV report breaking down campaign performance by site and day. Useful for identifying top-performing sites and daily trends.

```APIDOC
## GET /get_campaign_site_day_breakdown_report

### Description
Generates a detailed CSV report breaking down campaign performance by site and day. Useful for identifying top-performing sites and daily trends.

### Method
GET

### Endpoint
/get_campaign_site_day_breakdown_report

### Parameters
#### Query Parameters
- **account_id** (string) - Required - The ID of the advertiser account.
- **start_date** (string) - Required - The start date for the report (YYYY-MM-DD).
- **end_date** (string) - Required - The end date for the report (YYYY-MM-DD).
- **page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **page_size** (integer) - Optional - The number of records per page. Defaults to 50.
- **sort_field** (string) - Optional - The field to sort the report by (e.g., 'clicks', 'impressions').
- **sort_direction** (string) - Optional - The direction of sorting ('ASC' or 'DESC'). Defaults to 'DESC'.
- **filters** (object) - Optional - Filters to apply to the report.
  - **campaign_id** (string) - Optional - Filter by a specific campaign ID.

### Request Example
```json
{
    "name": "get_campaign_site_day_breakdown_report",
    "arguments": {
        "account_id": "advertiser_12345_prod",
        "start_date": "2024-01-15",
        "end_date": "2024-01-21",
        "page": 1,
        "page_size": 50,
        "sort_field": "clicks",
        "sort_direction": "DESC",
        "filters": {
            "campaign_id": "campaign_001"
        }
    }
}
```

### Response
#### Success Response (200)
- **report_data** (string) - CSV formatted report data.
- **report_summary** (object) - Contains pagination and total record information.
  - **page** (integer) - Current page number.
  - **page_size** (integer) - Records per page.
  - **total** (integer) - Total number of records.

#### Response Example
```csv
date,site_name,site_id,campaign_id,impressions,clicks,ctr,spent
2024-01-18,news-site.com,site_001,campaign_001,8500,340,4.00,85.00
2024-01-19,tech-blog.com,site_002,campaign_001,7200,288,4.00,72.00
```
```

--------------------------------

### PyPI Deployment - Package Configuration

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Information on deploying the Realize MCP Server as a PyPI package.

```APIDOC
## PyPI Deployment - Package Configuration

### Description
The Realize MCP Server is available as a PyPI package named `realize-mcp`, simplifying its deployment and integration.

### Method
Deployment / Installation

### Endpoint
PyPI Repository

### Parameters
#### Package Name
- **realize-mcp** (string) - The name of the package on PyPI.

### Request Example
```bash
pip install realize-mcp
```

### Response
#### Success Response (200)
The `realize-mcp` package is installed.

#### Response Example
N/A
```

--------------------------------

### Configure Realize MCP Server in Cursor IDE (JSON)

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Configuration for the Realize MCP server within the Cursor IDE. Supports both stdio and SSE transports, including OAuth 2.1 authentication.

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

```json
{
  "mcpServers": {
    "realize-mcp": {
      "url": "https://your-mcp-server.example.com/sse"
    }
  }
}
```

```json
{
  "mcpServers": {
    "realize-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/mcp-remote",
        "https://your-mcp-server.example.com/sse",
        "--transport",
        "sse"
      ]
    }
  }
}
```

--------------------------------

### GET /{account_id}/campaigns/{campaign_id}

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Retrieves detailed information for a specific campaign within a Taboola account.

```APIDOC
## GET /{account_id}/campaigns/{campaign_id}

### Description
Fetches metadata and status information for a specific campaign.

### Method
GET

### Endpoint
/{account_id}/campaigns/{campaign_id}

### Parameters
#### Path Parameters
- **account_id** (string) - Required - The unique identifier for the account
- **campaign_id** (string) - Required - The unique identifier for the campaign

### Response
#### Success Response (200)
- **id** (string) - Campaign ID
- **name** (string) - Campaign name
- **status** (string) - Current status (e.g., RUNNING, PAUSED)
- **budget** (float) - Campaign budget

#### Response Example
{
  "id": "123456",
  "name": "Summer Sale",
  "status": "RUNNING",
  "budget": 1000.0
}
```

--------------------------------

### Execute AI Assistant Workflow

Source: https://context7.com/taboola/realize-mcp/llms.txt

Demonstrates a sequential workflow to identify an account and retrieve associated campaign data. This pattern shows how to chain multiple MCP tool calls to fulfill complex user requests.

```python
search_accounts_call = {
    "name": "search_accounts",
    "arguments": {"query": "Marketing Corp"}
}

get_campaigns_call = {
    "name": "get_all_campaigns",
    "arguments": {"account_id": "mktg_corp_001"}
}
```

--------------------------------

### Verify Tool Registry and Server Functionality

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Python scripts to verify that tools are correctly registered and discoverable by the MCP registry, and to test the server entry point.

```python
from realize.tools.registry import get_all_tools
print('Tools:', len(get_all_tools()))
```

```python
import sys
sys.path.append('src')
from tools.registry import get_all_tools
print(f'Found {len(get_all_tools())} tools')
```

--------------------------------

### GET /get_campaign_history_report

Source: https://context7.com/taboola/realize-mcp/llms.txt

Retrieves a historical report for campaigns within a specified date range. Supports pagination for large datasets.

```APIDOC
## GET /get_campaign_history_report

### Description
Retrieves a historical report for campaigns within a specified date range. Supports pagination for large datasets.

### Method
GET

### Endpoint
/get_campaign_history_report

### Parameters
#### Query Parameters
- **account_id** (string) - Required - The ID of the advertiser account.
- **start_date** (string) - Required - The start date for the report (YYYY-MM-DD).
- **end_date** (string) - Required - The end date for the report (YYYY-MM-DD).
- **page** (integer) - Optional - The page number for pagination. Defaults to 1.
- **page_size** (integer) - Optional - The number of records per page. Defaults to 100.

### Request Example
```json
{
    "name": "get_campaign_history_report",
    "arguments": {
        "account_id": "advertiser_12345_prod",
        "start_date": "2024-01-01",
        "end_date": "2024-03-31",
        "page": 1,
        "page_size": 100
    }
}
```

### Response
#### Success Response (200)
- **report_data** (string) - CSV formatted report data.
- **report_summary** (object) - Contains pagination and total record information.
  - **page** (integer) - Current page number.
  - **page_size** (integer) - Records per page.
  - **total** (integer) - Total number of records.

#### Response Example
```csv
date,campaign_id,campaign_name,impressions,clicks,spent,conversions
2024-01-01,campaign_001,"Summer Sale 2024",15000,450,112.50,5
2024-01-02,campaign_001,"Summer Sale 2024",16500,495,123.75,6
```
```

--------------------------------

### Configure Stdio Transport for MCP Clients

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Configures the MCP server for local use via stdio. Requires providing client credentials as environment variables.

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

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

--------------------------------

### Cursor IDE - SSE Transport Configuration (OAuth 2.1)

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Configuration for the Realize MCP server using SSE transport in Cursor IDE, including OAuth 2.1 authentication flow.

```APIDOC
## Cursor IDE - SSE Transport Configuration (OAuth 2.1)

### Description
Configure the Realize MCP server to use SSE transport in Cursor IDE. This method involves directly specifying the SSE URL and relies on OAuth 2.1 with PKCE for authentication.

### Method
Configuration

### Endpoint
Cursor Settings → Features → Model Context Protocol

### Parameters
#### Request Body
- **mcpServers** (object) - Required - Configuration for MCP servers.
  - **realize-mcp** (object) - Required - Configuration for the realize-mcp server.
    - **url** (string) - Required - The SSE URL of your MCP server (e.g., `https://your-mcp-server.example.com/sse`).

### Request Example
```json
{
  "mcpServers": {
    "realize-mcp": {
      "url": "https://your-mcp-server.example.com/sse"
    }
  }
}
```

### Response
#### Success Response (200)
Configuration is applied directly by the IDE. Cursor will initiate an OAuth 2.1 flow on first use, opening a browser for authentication and storing the access token.

#### Response Example
N/A
```

--------------------------------

### VS Code - Add MCP Server

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Command to add the Realize MCP server to VS Code, specifying the execution command, arguments, and environment variables.

```APIDOC
## VS Code - Add MCP Server

### Description
Use this command to add the Realize MCP server to VS Code. It specifies the name, execution command, arguments, and environment variables required for the server to run.

### Method
Command Line

### Endpoint
VS Code Terminal

### Parameters
#### Command Line Arguments
- **--add-mcp** (string) - Required - A JSON string containing the MCP server configuration.
  - **name** (string) - Required - The name of the MCP server (e.g., `realize-mcp`).
  - **command** (string) - Required - The command to execute the server (e.g., `python`).
  - **args** (array) - Required - Arguments for the command, including the path to the server script.
    - **0** (string) - Required - Path to the Realize MCP server script (e.g., `/path/to/realize-mcp/src/realize_server.py`).
  - **env** (object) - Required - Environment variables for the server.
    - **REALIZE_CLIENT_ID** (string) - Required - Your client ID for authentication.
    - **REALIZE_CLIENT_SECRET** (string) - Required - Your client secret for authentication.

### Request Example
```bash
code --add-mcp '{"name":"realize-mcp","command":"python","args":["/path/to/realize-mcp/src/realize_server.py"],"env":{"REALIZE_CLIENT_ID":"your_id","REALIZE_CLIENT_SECRET":"your_secret"}}'
```

### Response
#### Success Response (200)
VS Code will start the specified MCP server.

#### Response Example
N/A
```

--------------------------------

### Cursor IDE - stdio Transport Configuration

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Configuration for the Realize MCP server using stdio transport within Cursor IDE. This includes the command to run the server and environment variables for authentication.

```APIDOC
## Cursor IDE - stdio Transport Configuration

### Description
Configure the Realize MCP server to use stdio transport in Cursor IDE. This involves specifying the server command and necessary environment variables for authentication.

### Method
Configuration

### Endpoint
Cursor Settings → Features → Model Context Protocol

### Parameters
#### Request Body
- **mcpServers** (object) - Required - Configuration for MCP servers.
  - **realize-mcp** (object) - Required - Configuration for the realize-mcp server.
    - **command** (string) - Required - The command to execute the MCP server (e.g., `realize-mcp-server`).
    - **env** (object) - Required - Environment variables for the server.
      - **REALIZE_CLIENT_ID** (string) - Required - Your client ID for authentication.
      - **REALIZE_CLIENT_SECRET** (string) - Required - Your client secret for authentication.

### Request Example
```json
{
  "mcpServers": {
    "realize-mcp": {
      "command": "realize-mcp-server",
      "env": {
        "REALIZE_CLIENT_ID": "your_client_id",
        "REALIZE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

### Response
#### Success Response (200)
Configuration is applied directly by the IDE.

#### Response Example
N/A
```

--------------------------------

### Cursor IDE - Alternative SSE Transport using mcp-remote

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Alternative configuration for SSE transport in Cursor IDE using `mcp-remote` as a bridge, useful when direct URL configuration is not working.

```APIDOC
## Cursor IDE - Alternative SSE Transport using mcp-remote

### Description
Provides an alternative configuration for SSE transport in Cursor IDE when direct URL configuration fails. This method uses `mcp-remote` to bridge the connection to your MCP server.

### Method
Configuration

### Endpoint
Cursor Settings → Features → Model Context Protocol

### Parameters
#### Request Body
- **mcpServers** (object) - Required - Configuration for MCP servers.
  - **realize-mcp** (object) - Required - Configuration for the realize-mcp server.
    - **command** (string) - Required - The command to execute (e.g., `npx`).
    - **args** (array) - Required - Arguments for the command, including the `mcp-remote` package and server URL.
      - **0** (string) - Required - `-y`.
      - **1** (string) - Required - `@modelcontextprotocol/mcp-remote`.
      - **2** (string) - Required - The SSE URL of your MCP server (e.g., `https://your-mcp-server.example.com/sse`).
      - **3** (string) - Required - `--transport`.
      - **4** (string) - Required - `sse`.

### Request Example
```json
{
  "mcpServers": {
    "realize-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/mcp-remote",
        "https://your-mcp-server.example.com/sse",
        "--transport",
        "sse"
      ]
    }
  }
}
```

### Response
#### Success Response (200)
Configuration is applied directly by the IDE.

#### Response Example
N/A
```

--------------------------------

### Generate Site/Day Performance Report (CSV)

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Generates a CSV report detailing site and day performance breakdown for campaigns. Requires `account_id`, `start_date`, and `end_date`. Supports optional sorting and filtering.

```python
def get_campaign_site_day_breakdown_report(account_id: str, start_date: str, end_date: str, page: int = 1, page_size: int = 20, sort_field: str = None, sort_direction: str = 'DESC', filters: dict = None):
    """Generate a site/day performance breakdown report in CSV format.

    Args:
        account_id: The unique identifier for the account (string).
        start_date: The start date for the report (YYYY-MM-DD).
        end_date: The end date for the report (YYYY-MM-DD).
        page: The page number for pagination (integer, default: 1).
        page_size: The number of results per page (integer, default: 20, max: 100).
        sort_field: Field to sort the report by (e.g., 'clicks', 'spent', 'impressions').
        sort_direction: Direction of sorting ('ASC' or 'DESC', default: 'DESC').
        filters: A JSON object with string values for filtering the report.

    Returns:
        A CSV formatted string representing the report.
    """
    # Implementation details would go here
    pass
```

--------------------------------

### Interact with HTTP Endpoints

Source: https://context7.com/taboola/realize-mcp/llms.txt

RESTful endpoints for system health, Prometheus metrics, and OAuth 2.1 configuration. Includes support for dynamic client registration and standard MCP JSON-RPC over HTTP.

```bash
curl -X GET https://your-mcp-server.example.com/health
curl -X GET https://your-mcp-server.example.com/metrics
curl -X GET https://your-mcp-server.example.com/.well-known/oauth-protected-resource
curl -X POST https://your-mcp-server.example.com/register -H "Content-Type: application/json" -d '{"client_name": "My MCP Client", "redirect_uris": ["http://localhost:3000/callback"]}'
curl -X POST https://your-mcp-server.example.com/mcp -H "Authorization: Bearer your_oauth_token" -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
```

--------------------------------

### Integrate Realize MCP Server with Claude Code CLI

Source: https://context7.com/taboola/realize-mcp/llms.txt

Adds the Realize MCP server to Claude Code using the command line interface. Supports both stdio transport for local use and HTTP transport for production environments.

```bash
# Stdio transport (single-user, local)
claude mcp add realize-mcp --transport stdio \
  -e REALIZE_CLIENT_ID=your_client_id \
  -e REALIZE_CLIENT_SECRET=your_client_secret \
  -- realize-mcp-server

# HTTP transport (multi-user, production)
claude mcp add --transport http --callback-port 3000 \
  realize-mcp https://your-mcp-server.example.com/mcp
```

--------------------------------

### Enable Debug Mode for Taboola Realize-MCP

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Configures the server to output detailed logs, including API request/response traces and MCP protocol messages, to assist in troubleshooting.

```bash
export LOG_LEVEL=DEBUG
python src/realize_server.py
```

--------------------------------

### Realize MCP Server - Streamable HTTP Transport

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Details on setting up the Realize MCP Server with Streamable HTTP transport for multi-user deployments, utilizing OAuth 2.1 for authentication.

```APIDOC
## Realize MCP Server - Streamable HTTP Transport

### Description
This section outlines the installation and client configuration for the Realize MCP Server using the Streamable HTTP transport. This transport is designed for multi-user environments and relies on OAuth 2.1 for authentication, making it suitable for stateless deployments and Kubernetes.

### Installation

```bash
pip install realize-mcp
```

### Start the Server

Set the `MCP_TRANSPORT` and `OAUTH_DCR_CLIENT_ID` environment variables before running the server.

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

### Client Setup Examples

**Claude Desktop:**

1.  Navigate to Settings → Connectors → Add Custom Connector.
2.  Enter the MCP Server name and URL (e.g., `https://your-mcp-server.example.com/mcp`).
3.  Click **Connect** to initiate the OAuth 2.1 flow. You will be redirected to Taboola SSO to authenticate and obtain a bearer token.

**Claude Code (CLI):**

```bash
claude mcp add --transport http --callback-port 3000 realize-mcp https://your-mcp-server.example.com/mcp
```

**Cursor IDE:**

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

### Endpoints

*   **`GET /.well-known/oauth-protected-resource`**
    *   **Description:** RFC 9728 Protected Resource Metadata. Supports path-based discovery.
    *   **Method:** GET
    *   **Endpoint:** `/.well-known/oauth-protected-resource`

*   **`GET /.well-known/oauth-authorization-server`**
    *   **Description:** RFC 8414 metadata. The `registration_endpoint` is rewritten.
    *   **Method:** GET
    *   **Endpoint:** `/.well-known/oauth-authorization-server`

*   **`POST /register`**
    *   **Description:** RFC 7591 Dynamic Client Registration.
    *   **Method:** POST
    *   **Endpoint:** `/register`

*   **`POST|GET|DELETE /mcp`**
    *   **Description:** The main MCP Streamable HTTP endpoint. Requires a Bearer token for authentication.
    *   **Method:** POST, GET, DELETE
    *   **Endpoint:** `/mcp`

*   **`GET /health`**
    *   **Description:** Health check endpoint, typically used for Kubernetes probes.
    *   **Method:** GET
    *   **Endpoint:** `/health`

*   **`GET /metrics`**
    *   **Description:** Prometheus metrics endpoint for monitoring.
    *   **Method:** GET
    *   **Endpoint:** `/metrics`
```

--------------------------------

### Add Realize MCP Server to VS Code (Bash)

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Command to add the Realize MCP server to VS Code using the `code --add-mcp` command. This specifies the command to run the server and its environment variables.

```bash
code --add-mcp '{"name":"realize-mcp","command":"python","args":["/path/to/realize-mcp/src/realize_server.py"],"env":{"REALIZE_CLIENT_ID":"your_id","REALIZE_CLIENT_SECRET":"your_secret"}}'
```

--------------------------------

### Generate Top Content Report (Python)

Source: https://context7.com/taboola/realize-mcp/llms.txt

This snippet demonstrates how to configure a call to generate a top content report. It specifies the report name, account ID, date range, page size, and sorting criteria. The expected output is a CSV report.

```python
get_report_call = {
    "name": "get_top_campaign_content_report",
    "arguments": {
        "account_id": "mktg_corp_001",
        "start_date": "2024-01-01",
        "end_date": "2024-01-31",
        "page_size": 20,
        "sort_field": "spent",
        "sort_direction": "DESC"
    }
}
# Response: CSV report with top 20 content items by spend
```

--------------------------------

### Retrieve Specific Campaign Item Details

Source: https://context7.com/taboola/realize-mcp/llms.txt

Fetches detailed information for a single campaign creative item. Provides approval status and granular performance data for the specified item.

```JSON
{
    "name": "get_campaign_item",
    "arguments": {
        "account_id": "advertiser_12345_prod",
        "campaign_id": "campaign_001",
        "item_id": "item_001"
    }
}
```

--------------------------------

### Search Accounts

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Searches for accounts based on a given query (e.g., company name or numeric ID). This is a prerequisite for obtaining the `account_id` required by other campaign and reporting tools. Never use raw numeric IDs directly with other tools.

```python
def search_accounts(query: str):
    """Searches for accounts based on a query string.

    Args:
        query: The search term (e.g., company name or numeric ID).

    Returns:
        A list of account objects, each containing an `account_id`.
    """
    # Implementation details would go here
    pass
```

--------------------------------

### Configure Realize MCP Server for Stdio Transport

Source: https://context7.com/taboola/realize-mcp/llms.txt

Configures the MCP server for local, single-user deployments using stdio transport. It requires client credentials for authentication.

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

--------------------------------

### Handle Account ID Validation Errors

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Demonstrates the required workflow for resolving numeric account ID errors by using the search_accounts tool to retrieve the correct account_id.

```text
Error: This appears to be a numeric account ID (12345). Please use the search_accounts tool first 
to get the proper account_id field value. REQUIRED WORKFLOW: 
1) search_accounts('12345') 2) Extract 'account_id' field from response 3) Use that account_id value instead
```

--------------------------------

### POST /oauth/token

Source: https://github.com/taboola/realize-mcp/blob/main/design.md

Authenticates the client and retrieves an access token using OAuth 2.0 client credentials.

```APIDOC
## POST /oauth/token

### Description
Retrieves an access token required for subsequent API requests using client credentials.

### Method
POST

### Endpoint
/oauth/token

### Request Body
- **grant_type** (string) - Required - Must be 'client_credentials'
- **client_id** (string) - Required - Your application client ID
- **client_secret** (string) - Required - Your application client secret

### Request Example
{
  "grant_type": "client_credentials",
  "client_id": "your_id",
  "client_secret": "your_secret"
}

### Response
#### Success Response (200)
- **access_token** (string) - The JWT access token
- **token_type** (string) - Type of token
- **expires_in** (integer) - Expiration time in seconds

#### Response Example
{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

--------------------------------

### Generate Campaign Performance Report (CSV)

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Generates a CSV report detailing campaign performance. Requires `account_id`, `start_date`, and `end_date`. Supports optional sorting and filtering parameters. Returns CSV data with a summary header.

```python
def get_campaign_breakdown_report(account_id: str, start_date: str, end_date: str, page: int = 1, page_size: int = 20, sort_field: str = None, sort_direction: str = 'DESC', filters: dict = None):
    """Generate a campaign performance breakdown report in CSV format.

    Args:
        account_id: The unique identifier for the account (string).
        start_date: The start date for the report (YYYY-MM-DD).
        end_date: The end date for the report (YYYY-MM-DD).
        page: The page number for pagination (integer, default: 1).
        page_size: The number of results per page (integer, default: 20, max: 100).
        sort_field: Field to sort the report by (e.g., 'clicks', 'spent', 'impressions').
        sort_direction: Direction of sorting ('ASC' or 'DESC', default: 'DESC').
        filters: A JSON object with string values for filtering the report.

    Returns:
        A CSV formatted string representing the report.
    """
    # Implementation details would go here
    pass
```

--------------------------------

### Generate Top Campaign Content Report (CSV)

Source: https://github.com/taboola/realize-mcp/blob/main/README.md

Generates a CSV report for top-performing campaign content. Requires `account_id`, `start_date`, and `end_date`. Supports sorting parameters. Returns CSV data with a summary header.

```python
def get_top_campaign_content_report(account_id: str, start_date: str, end_date: str, page: int = 1, page_size: int = 20, sort_field: str = None, sort_direction: str = 'DESC'):
    """Generate a report on top performing campaign content in CSV format.

    Args:
        account_id: The unique identifier for the account (string).
        start_date: The start date for the report (YYYY-MM-DD).
        end_date: The end date for the report (YYYY-MM-DD).
        page: The page number for pagination (integer, default: 1).
        page_size: The number of results per page (integer, default: 20, max: 100).
        sort_field: Field to sort the report by (e.g., 'clicks', 'spent', 'impressions').
        sort_direction: Direction of sorting ('ASC' or 'DESC', default: 'DESC').

    Returns:
        A CSV formatted string representing the report.
    """
    # Implementation details would go here
    pass
```

--------------------------------

### Retrieve Campaign Creative Items

Source: https://context7.com/taboola/realize-mcp/llms.txt

Retrieves a list of all creative items (ads) associated with a campaign. Returns metadata such as titles, URLs, thumbnails, and individual item performance metrics.

```JSON
{
    "name": "get_campaign_items",
    "arguments": {
        "account_id": "advertiser_12345_prod",
        "campaign_id": "campaign_001"
    }
}
```
Tokens:
Raw