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

, etc.) exposed by the connected agent.

Overview

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

Task

Purpose

Response Time

get_products

Discover inventory using natural language

~60s

list_authorized_properties

See publisher properties

~1s

list_creative_formats

View creative specifications

~1s

create_media_buy

Create campaigns

Minutes-Days

update_media_buy

Modify campaigns

Minutes-Days

sync_creatives

Upload creative assets

Minutes-Days

list_creatives

Query creative library

~1s

get_media_buy_delivery

Get performance data

~60s

Typical Workflow

Discover products

:

get_products

with a natural language brief

Review formats

:

list_creative_formats

to understand creative requirements

Create campaign

:

create_media_buy

with selected products and budget

Upload creatives

:

sync_creatives

to add creative assets

Monitor delivery

:

get_media_buy_delivery

to track performance

Task Reference

get_products

Discover advertising products using natural language briefs.

Request:

{

"buying_mode"

:

"brief"

,

"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:

buying_mode

(string): Required discriminator -

"brief"

or

"wholesale"

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

file.

Format IDs

Creative format identifiers are structured objects:

{

"format_id"

:

{

"agent_url"

:

"https://creative.adcontextprotocol.org"

,

"id"

:

"display_300x250"

}

}

The

agent_url

specifies which creative agent defines the format. Use

https://creative.adcontextprotocol.org

for standard IAB formats.

Pricing Options

Products include

pricing_options

array. Each option has:

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

in your package.

Asynchronous Operations

Operations like

create_media_buy

and

sync_creatives

may require human approval. The response includes:

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.