Skip to content

Developer Setup Guide

Set up the buyer agent infrastructure, connect to seller agents and SSPs, and generate credentials for your media buying team to use in Claude Desktop.

Prerequisites

  • Python 3.11+
  • Docker (for deployment)
  • Seller agent URLs (at least one seller must be reachable)
  • SSP API keys (optional: PubMatic, Magnite, Index Exchange)
  • Anthropic API key

Step 1: Deploy the Buyer Agent

# Clone and install
git clone https://github.com/IABTechLab/buyer-agent.git
cd buyer-agent
pip install -e .

# Or with Docker
cd infra/docker
docker compose up

Step 2: Configure Environment

Create a .env file:

# Required
ANTHROPIC_API_KEY=sk-ant-...

# Buyer Identity
IAB_SERVER_URL=http://localhost:8001

# Storage (SQLite)
DATABASE_URL=sqlite:///./ad_buyer.db

# Environment
ENVIRONMENT=development
LOG_LEVEL=INFO

Step 3: Connect to Sellers

Set the SELLER_ENDPOINTS variable to a comma-separated list of seller agent MCP URLs:

# Single seller
SELLER_ENDPOINTS=http://localhost:3000

# Multiple sellers
SELLER_ENDPOINTS=http://espn.example.com,http://conde.example.com,http://nytimes.example.com

Each URL should point to a running seller agent. The buyer will use these endpoints for inventory discovery, deal negotiation, and order management.

Verify seller connectivity

After starting the buyer agent, run:

curl http://localhost:8001/health

This returns {"status": "healthy", "version": "1.0.0"} when the service is up. To see per-service detail — including how many seller endpoints are configured — call the health_check MCP tool from your connected MCP client (it reports database, seller_connections with an endpoint count, and event_bus).

Step 4: Configure SSP Connectors (Optional)

If your media buyers need to import deals from SSPs directly, configure the connector credentials (see SSP Connector Setup for the per-SSP variables):

# Example: PubMatic
PUBMATIC_API_TOKEN=your-bearer-token
PUBMATIC_SEAT_ID=your-seat-id

The buyer agent's SSP connector tools (list_ssp_connectors, import_deals_ssp, test_ssp_connection) can be called by the business team once credentials are in place.

Step 5: Configure Optional Services

# CORS (if browser clients need access)
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8080

# LLM model overrides (optional)
DEFAULT_LLM_MODEL=anthropic/claude-sonnet-4-5-20250929
MANAGER_LLM_MODEL=anthropic/claude-opus-4-8

Step 6: Start the Server

uvicorn ad_buyer.interfaces.api.main:app --host 0.0.0.0 --port 8001

Verify: curl http://localhost:8001/health

Step 7: Generate Operator Credentials

Create an inbound API key for your business team. Set API_KEY in your .env:

# Inbound API key — business team will use this in Claude Desktop
# Leave empty to disable auth (development only)
API_KEY=sk-operator-XXXXX

Generate a strong random key: python -c "import secrets; print('sk-operator-' + secrets.token_urlsafe(32))"

Restart the server after setting API_KEY. All incoming requests (REST and MCP alike) must now carry the key in the X-API-Key header — the buyer agent does not accept Authorization: Bearer tokens.

Step 8: Hand Off

Give your media buying team:

  1. MCP URL: http://your-server:8001/mcp/ (Streamable HTTP, canonical — or your public URL)
  2. API key: the value you set in API_KEY

They'll connect Claude Desktop using the Claude Desktop Setup Guide and complete the business configuration (deal templates, approval thresholds, seller API keys) through the interactive setup wizard.

Verify the Full Setup

# Health check
curl http://localhost:8001/health

# MCP smoke test (add -H "X-API-Key: $API_KEY" if API_KEY is set)
curl -s -X POST http://localhost:8001/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}'
# Legacy SSE (older clients only): curl -N http://localhost:8001/mcp-sse/sse

Expected health response:

{
  "status": "healthy",
  "version": "1.0.0"
}

For a configured/missing breakdown of the setup itself, call the get_setup_status MCP tool from a connected client (there is no REST setup-status route). For per-service health detail, call the health_check MCP tool.