AdCP Media Buy Protocol

This skill enables you to execute the AdCP Media Buy Protocol with sales agents. Use the standard MCP tools (

get_products

create_media_buy

sync_creatives

Overview

The Media Buy Protocol provides 8 standardized tasks for managing advertising campaigns:

get_products

list_authorized_properties

list_creative_formats

create_media_buy

update_media_buy

sync_creatives

list_creatives

get_media_buy_delivery

Typical Workflow

1. Discover products:

   get_products

   with a natural language brief
2. Review formats:

   list_creative_formats

   to understand creative requirements
3. Create campaign:

   create_media_buy

   with selected products and budget
4. Upload creatives:

   sync_creatives

   to add creative assets
5. Monitor delivery:

   get_media_buy_delivery

   to track performance

Task Reference

get_products

Discover advertising products using natural language briefs.

Request:

{
  "brief": "Looking for premium video inventory for a tech brand targeting developers",
  "brand": {
    "domain": "example.com"
  },
  "filters": {
    "channels": ["video", "ctv"],
    "budget_range": { "min": 5000, "max": 50000 }
  }
}

Key fields:

• brief

  (string): Natural language description of campaign requirements

• brand

  (object): Brand identity -

  { "domain": "acmecorp.com" }

• filters

  (object, optional): Filter by channels, budget, delivery_type, format_types

Response contains:

• products

  : Array of matching products with

  product_id

  ,

  name

  ,

  description

  ,

  pricing_options

• Each product includes

  format_ids

  (supported creative formats) and

  targeting

  (available targeting)

list_authorized_properties

Get the list of publisher properties this agent can sell.

Request:

{}

No parameters required.

Response contains:

• publisher_domains

  : Array of domain strings the agent is authorized to sell

list_creative_formats

View supported creative specifications.

Request:

{
  "format_types": ["video", "display"]
}

Key fields:

• format_types

  (array, optional): Filter to specific format categories

Response contains:

• formats

  : Array of format specifications with dimensions, requirements, and asset schemas

create_media_buy

Create an advertising campaign from selected products.

Request:

{
  "buyer_ref": "campaign-2024-q1-001",
  "brand": {
    "domain": "acme.com"
  },
  "packages": [
    {
      "buyer_ref": "pkg-video-001",
      "product_id": "premium_video_30s",
      "pricing_option_id": "cpm-standard",
      "budget": 10000
    }
  ],
  "start_time": {
    "type": "asap"
  },
  "end_time": "2024-03-31T23:59:59Z"
}

Key fields:

• buyer_ref

  (string, required): Your unique identifier for this campaign

• brand

  (object, required): Brand identity -

  { "domain": "acmecorp.com" }

• packages

  (array, required): Products to purchase, each with:

  • buyer_ref

    : Your identifier for this package

  • product_id

    : From

    get_products

    response

  • pricing_option_id

    : From product's

    pricing_options

  • budget

    : Amount in dollars

  • bid_price

    : Required for auction pricing

  • targeting_overlay

    : Additional targeting constraints

  • creative_ids

    or

    creatives

    : Creative assignments

• start_time

  (object, required):

  { "type": "asap" }

  or

  { "type": "scheduled", "datetime": "..." }

• end_time

  (string, required): ISO 8601 datetime

Response contains:

• media_buy_id

  : The created campaign identifier

• status

  : Current state (often

  pending

  for async approval)

• packages

  : Created packages with their IDs

update_media_buy

Modify an existing campaign.

Request:

{
  "media_buy_id": "mb_abc123",
  "updates": {
    "budget_change": 5000,
    "end_time": "2024-04-30T23:59:59Z",
    "status": "paused"
  }
}

Key fields:

• media_buy_id

  (string, required): The campaign to update

• updates

  (object): Changes to apply - budget_change, end_time, status, targeting, etc.

sync_creatives

Upload and manage creative assets.

Request:

{
  "creatives": [
    {
      "creative_id": "hero_video_30s",
      "name": "Brand Hero Video",
      "format_id": {
        "agent_url": "https://creative.adcontextprotocol.org",
        "id": "video_standard_30s"
      },
      "assets": {
        "video": {
          "url": "https://cdn.example.com/hero.mp4",
          "width": 1920,
          "height": 1080,
          "duration_ms": 30000
        }
      }
    }
  ],
  "assignments": {
    "hero_video_30s": ["pkg_001", "pkg_002"]
  }
}

Key fields:

• creatives

  (array, required): Creative assets to sync

  • creative_id

    : Your unique identifier

  • format_id

    : Object with

    agent_url

    and

    id

    from format specifications

  • assets

    : Asset content (video, image, html, etc.)

• assignments

  (object, optional): Map creative_id to package IDs

• dry_run

  (boolean): Preview changes without applying

• delete_missing

  (boolean): Archive creatives not in this sync

list_creatives

Query the creative library with filtering.

Request:

{
  "filters": {
    "status": ["active"],
    "format_types": ["video"]
  },
  "limit": 20
}

get_media_buy_delivery

Retrieve performance metrics for a campaign.

Request:

{
  "media_buy_id": "mb_abc123",
  "granularity": "daily",
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  }
}

Response contains:

• delivery

  : Aggregated metrics (impressions, spend, clicks, etc.)

• by_package

  : Breakdown by package

• timeseries

  : Data points over time if granularity specified

Key Concepts

Brand identity

Brand context is provided by domain reference:

{
  "brand": {
    "domain": "acmecorp.com"
  }
}

The agent resolves the domain to retrieve the brand's identity (name, colors, guidelines, etc.) from its

brand.json

Format IDs

Creative format identifiers are structured objects:

{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_300x250"
  }
}

The

agent_url

https://creative.adcontextprotocol.org

Pricing Options

Products include

pricing_options

• pricing_option_id

  : Use this in

  create_media_buy

• pricing_model

  : "cpm", "cpm-auction", "flat-fee", etc.

• price

  : Base price (for fixed pricing)

• floor

  : Minimum bid (for auction)

For auction pricing, include

bid_price

Asynchronous Operations

Operations like

create_media_buy

sync_creatives

• status: "pending"

  - Operation awaiting approval

• task_id

  - For tracking async progress

Poll or use webhooks to check completion status.

Error Handling

Common error patterns:

• 400 Bad Request: Invalid parameters - check required fields
• 401 Unauthorized: Invalid or missing authentication token
• 404 Not Found: Invalid product_id, media_buy_id, or creative_id
• 422 Validation Error: Schema validation failure - check field types

Error responses include:

{
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "budget must be greater than 0",
      "field": "packages[0].budget"
    }
  ]
}

Testing Mode

For testing without real transactions, agents may support:

• X-Dry-Run: true

  header - Preview without side effects
• Test products with

  test: true

  flag
• Sandbox environments

Ask the agent about testing capabilities before creating real campaigns.