Audience Manager MCP Server

A production-grade Model Context Protocol (MCP) server that transforms SambaTV's Audience Manager 2.0 complex UI workflows into natural language-driven segment creation.

Overview

This MCP server implements the complete MCP framework with all three core primitives:

• 6 Tools (Model-controlled) - Claude decides when to call
• 6 Resources (App-controlled) - Static data for context
• 4 Prompts (User-controlled) - Slash commands for workflows

Quick Start

Prerequisites

• Python 3.11+
• uv package manager
• API credentials for Audience Manager staging environment

Installation

# Install dependencies
uv sync

# Configure environment
cp docs/.env.template .env
# Edit .env with your API credentials

# Test installation
PYTHONPATH=src uv run python -c "from custom_server.core import create_mcp_server; print('✅ Server created:', create_mcp_server().name)"

Development Modes

1. Stdio Mode (Claude Desktop Integration)

# Start stdio server
PYTHONPATH=src uv run python src/custom_server/stdio_server.py

# Or use the wrapper script
./run_mcp_server.sh

2. HTTP Mode (Development Testing)

# Start HTTP server with auto-reload
uv run uvicorn src.custom_server.app:app --port 8000 --reload

3. MCP Inspector (Interactive Testing)

# Local stdio testing
npx @modelcontextprotocol/inspector ./run_stdio.sh

# Cloud deployment testing
./run_inspector_cloud.sh audience-manager-mcp-staging

Production Deployment

Google Cloud Run (Live Production)

Public URL: https://audience-manager-mcp-201626763325.us-central1.run.app/mcp

# Deploy to Cloud Run
export AUTH_STRATEGY="none"
./deploy-to-cloudrun.sh ai-workflows-459123

# Users can add to Claude Code:
claude mcp add --transport http audience-manager https://audience-manager-mcp-201626763325.us-central1.run.app/mcp

Databricks Apps (Enterprise Deployment)

Live URL: https://mcp-audience-manager-8589181270079680.aws.databricksapps.com

# Build and deploy
uv build --wheel
databricks auth login --profile samba-workspace
databricks workspace import-dir .build/ "/Users/your.name@samba.tv/mcp-audience-manager" --overwrite
databricks apps deploy mcp-audience-manager --source-code-path "/Workspace/Users/your.name@samba.tv/mcp-audience-manager"

MCP Architecture

Tools (Model-Controlled)

Claude automatically invokes these tools based on user requests:

1. audience_details() - Configure all 11 Bridge UI Step 1 fields
2. audience_search() - Search shows, ads, products, games with full metadata
3. audience_create() - Create audience with merged configurations
4. audience_activate() - Configure precision and activate to DSP platforms
5. audience_standard() - Get pre-built audience templates
6. audience_debug() - API response structure investigation

Resources (App-Controlled)

Static data accessible via @audiencemanager:// URIs:

1. workflow-templates - Industry-specific templates
2. bridge-workflow-guide - Complete Bridge UI → MCP mapping
3. troubleshooting-guide - Issue resolution procedures
4. content-discovery-guide - Advanced targeting strategies
5. api-payload-examples - Complete API examples
6. schema-debugging-guide - Schema validation procedures

Prompts (User-Controlled)

Slash commands for guided workflows:

1. /audience_onboarding_guide - Bridge UI → MCP transition
2. /segment_creation_workflow - Complete 5-step process
3. /advanced_targeting_strategies - Complex boolean logic
4. /troubleshooting_segments - Problem diagnosis

Project Structure

custom-server/
├── src/custom_server/
│   ├── core/                   # Core MCP implementation
│   │   ├── server.py          # MCP server factory
│   │   ├── tools.py           # Tool implementations
│   │   ├── config.py          # API client & configuration
│   │   ├── mcp_prompts_resources.py  # Prompts & resources
│   │   └── resources.py       # Resource management
│   │
│   ├── stdio_server.py        # Stdio transport (Claude Desktop)
│   ├── app.py                 # HTTP transport (FastAPI)
│   ├── main.py                # Server entry point
│   ├── cloudrun_server.py     # Cloud Run implementation
│   └── databricks_config.py   # Databricks configuration
│
├── docs/                       # Comprehensive documentation
│   ├── reference/             # API specs and schemas
│   ├── guides/                # User and developer guides
│   ├── architecture/          # System design docs
│   ├── deployment/            # Deployment guides
│   ├── troubleshooting/       # Debug guides
│   ├── tool-descriptions/     # Individual tool docs
│   ├── specs/                 # OpenAPI specifications
│   └── archived/              # Historical documentation
│
├── pyproject.toml             # Python project configuration
├── .env                       # Environment variables (create from template)
├── run_mcp_server.sh         # Stdio server wrapper script
└── deploy-to-cloudrun.sh     # Cloud Run deployment script

Key Features

Complete Bridge UI Workflow Coverage

• All 11 Step 1 fields exposed via audience_details()
• Multi-category parallel search (shows, ads, products, games)
• Boolean logic support (AND/OR/NOT operations)
• 5-level precision/scale tradeoff configuration
• Multi-platform DSP activation (TradeDesk, Meta, Magnite, etc.)

Backend Compatibility

• Prisma ORM Integration: Full relationship handling
• 3-Tier Fallback Strategy: Primary/Secondary/Tertiary endpoints
• Enhanced Error Handling: Specific error detection and user-friendly messages
• Schema Compliance: OpenAPI 3.1.0 strict validation

Production Ready

• Zero Authentication: Public Cloud Run deployment (no token management)
• Auto-scaling: Google Cloud Run handles load automatically
• Multi-platform: Databricks Apps + Google Cloud Run
• 99.9% Uptime: Enterprise-grade reliability

Configuration

Environment Variables

Create .env from template and configure:

# Core API Configuration
AUDIENCE_API_BASE_URL="https://segments-api.stg.cap.mysamba.tv"
AUDIENCE_API_TOKEN="your_token"
AUDIENCE_API_PASSWORD="your_password"

# Default Configuration
DEFAULT_DATA_SOURCES="samba_acr,stb"
DEFAULT_ADVERTISER_ID=1
DEFAULT_MINIMUM_AUDIENCE_SIZE=100000

# Processing Configuration
PROCESSING_TIMEOUT_MS=30000
MAX_CRITERIA_COMPLEXITY=10

# Prisma Backend Compatibility
STAGING_USER_ID=1
STAGING_ORGANIZATION_ID=1
USE_PRISMA_RELATIONS=true

# Reliability & Fallback Strategies
FALLBACK_STRATEGIES_ENABLED=true
FALLBACK_ENDPOINTS="segments,audiences,drafts"

# Debugging
DEBUG_API_PAYLOADS=true
LOG_API_RESPONSES=true
DEBUG_SEARCH_RESPONSES=true
LOG_LEVEL=INFO

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "audience-manager": {
      "command": "/path/to/audience-manager-mcp/custom-server/run_mcp_server.sh",
      "args": [],
      "env": {
        "AUDIENCE_API_BASE_URL": "https://segments-api.stg.cap.mysamba.tv",
        "AUDIENCE_API_TOKEN": "your_token",
        "AUDIENCE_API_PASSWORD": "your_password"
      }
    }
  }
}

Testing

Unit Tests

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_tools.py

# Run with coverage
uv run pytest --cov=custom_server

Integration Testing

# Test MCP server creation
PYTHONPATH=src uv run python -c "from custom_server.core import create_mcp_server; print('✅ Server created')"

# Test tool registration
PYTHONPATH=src uv run python -c "from custom_server.core.tools import register_all_tools; print('✅ Tools registered')"

# Test with MCP Inspector
npx @modelcontextprotocol/inspector ./run_stdio.sh

Documentation

Essential Documentation

• API Specifications - Complete API reference
• Schema Compliance - API schema requirements
• Architecture Guide - System architecture
• MCP Tools Guide - Tool reference
• System Prompt - Claude configuration

Deployment Documentation

• Google Cloud Run Guide - Cloud deployment
• Databricks Apps Guide - Enterprise deployment
• Local Development - Development setup

Troubleshooting

• Common Issues - FAQ and solutions
• Authentication Issues - Auth debugging
• Search API Errors - Search debugging

Example Workflows

Competitive Conquesting Campaign

User: "Create a competitive conquesting segment for Nike targeting Adidas viewers"

MCP Flow:
1. audience_details() → Configure campaign parameters
2. audience_search("Adidas commercials", "ads") → Find Adidas content
3. audience_create(config with Adidas viewers) → Create segment
4. audience_activate(segment_id, precision="moderate", platforms=["tradedesk", "meta"])

Result: "Nike_CC_Adidas_Q1_2025" segment activated to TradeDesk and Meta

Content-Based Audience Building

User: "Target premium drama viewers who stream content"

MCP Flow:
1. audience_details() → Configure audience parameters
2. audience_search("premium drama", "series") → Find drama content
3. audience_create(config with drama + streaming platforms)
4. audience_activate(segment_id, precision="balanced")

Result: "Premium_Drama_Streaming_Q1_2025" segment created

Success Metrics

This MCP server targets:

• 70% reduction in audience setup time
• 80% fewer failed audience generations
• Enable non-experts to create effective audiences
• 3x throughput with same headcount

Contributing

Development Workflow

1. Create feature branch from main
2. Implement changes with tests
3. Update documentation
4. Submit pull request with description
5. Pass CI/CD checks
6. Request code review

Code Standards

• Follow PEP 8 style guidelines
• Write comprehensive docstrings
• Include type hints
• Add unit tests for new features
• Update relevant documentation

Documentation Standards

• Keep docs synchronized with code
• Use lowercase hyphen-separated filenames
• Include practical examples
• Provide troubleshooting guidance
• Link to related documentation

Support

Getting Help

• Documentation: Check docs/ directory first
• Troubleshooting: Review docs/troubleshooting/
• Examples: See workflow examples in README
• Issues: Create GitHub issue with reproduction steps

Reporting Bugs

Include in bug reports:

1. MCP server version
2. Deployment environment (stdio/HTTP/Cloud Run/Databricks)
3. Steps to reproduce
4. Expected vs. actual behavior
5. Relevant logs and error messages

License

[Add license information]

Version History

• 2.0.0 (2025-10) - Complete documentation reorganization
• 1.9.0 (2025-09) - Google Cloud Run public deployment
• 1.8.0 (2025-09) - Databricks Apps deployment
• 1.7.0 (2025-01) - 6-tool architecture with activation
• 1.0.0 (2024-10) - Initial MCP server release

---

Maintained by: Audience Manager MCP Development Team Last Updated: 2025-10-09