Audience Manager MCP
MCP server for Audience Manager 2.0 - transforms Bridge UI workflows into natural language audience segment creation
Ask AI about Audience Manager MCP
Powered by Claude Β· Grounded in docs
I know everything about Audience Manager MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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+
uvpackage 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:
audience_details()- Configure all 11 Bridge UI Step 1 fieldsaudience_search()- Search shows, ads, products, games with full metadataaudience_create()- Create audience with merged configurationsaudience_activate()- Configure precision and activate to DSP platformsaudience_standard()- Get pre-built audience templatesaudience_debug()- API response structure investigation
Resources (App-Controlled)
Static data accessible via @audiencemanager:// URIs:
workflow-templates- Industry-specific templatesbridge-workflow-guide- Complete Bridge UI β MCP mappingtroubleshooting-guide- Issue resolution procedurescontent-discovery-guide- Advanced targeting strategiesapi-payload-examples- Complete API examplesschema-debugging-guide- Schema validation procedures
Prompts (User-Controlled)
Slash commands for guided workflows:
/audience_onboarding_guide- Bridge UI β MCP transition/segment_creation_workflow- Complete 5-step process/advanced_targeting_strategies- Complex boolean logic/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
- Create feature branch from
main - Implement changes with tests
- Update documentation
- Submit pull request with description
- Pass CI/CD checks
- 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:
- MCP server version
- Deployment environment (stdio/HTTP/Cloud Run/Databricks)
- Steps to reproduce
- Expected vs. actual behavior
- 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
