| name | build-retail-media-agent |
| description | Use when building an AdCP retail media network agent in Go — sells on-site placements, supports product catalogs, tracks conversions. |
Build a Retail Media Agent (Go)
Status: Validated against storyboard runner. If validation fails, check the common mistakes table first, then file an issue.
Overview
A retail media agent sells advertising on a retailer's properties. It extends the standard seller with catalog sync, event tracking, and performance feedback.
Before Writing Code
- Products. Each needs: product_id, name, description (required), channel, delivery_type, pricing_options, publisher_properties, format_ids, and reporting_capabilities. Use lowercase pricing models.
- Catalogs. What product feeds? How connected to ad rendering?
- Events. What conversion events? Purchase, add_to_cart, page_view?
- Approval workflow. Instant or async. Async SHOULD emit signed webhooks when the buyer supplies
push_notification_config — see skills/build-webhook-publisher/ for the emission pattern.
Tool Registration
Use adcp.AddTool for all 13 tools.
Tools and Response Shapes
1. get_adcp_capabilities — MUST include conversion_tracking
adcp.AddTool(server, "get_adcp_capabilities", "Agent capabilities",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.EmptyInput) (*mcp.CallToolResult, any, error) {
return adcp.CapabilitiesResponse(&adcp.CapabilitiesData{
ADCP: &adcp.ADCPVersion{MajorVersions: []int{3}},
SupportedProtocols: []string{"media_buy", "conversion_tracking", "compliance_testing"},
})
})
2. sync_accounts
adcp.AddTool(server, "sync_accounts", "Register accounts",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.SyncAccountsRequest) (*mcp.CallToolResult, any, error) {
var results []adcp.AccountResult
for i, acct := range input.Accounts {
id := fmt.Sprintf("acct-%s-%d", acct.Brand.Domain, i+1)
results = append(results, adcp.AccountResult{
AccountID: id, Brand: acct.Brand, Operator: acct.Operator,
Action: "created", Status: "active",
})
}
return adcp.SyncAccountsResponse(results, true)
})
3. sync_governance
adcp.AddTool(server, "sync_governance", "Register governance agents",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.SyncGovernanceRequest) (*mcp.CallToolResult, any, error) {
var results []adcp.GovernanceResult
for _, acct := range input.Accounts {
govAcct := acct.Account
if govAcct == nil {
govAcct = &adcp.GovernanceAccount{Brand: acct.Brand, Operator: acct.Operator}
}
results = append(results, adcp.GovernanceResult{
Account: govAcct, Status: "synced", GovernanceAgents: acct.GovernanceAgents,
})
}
return adcp.GovernanceResponse(results)
})
4. get_products
var products = []adcp.Product{
{
ProductID: "sponsored-product", Name: "Sponsored Product",
Description: "Promoted product listings in search results",
Channels: []string{"retail_media"}, DeliveryType: "non_guaranteed",
PublisherProperties: []adcp.PublisherPropertySelector{
{PublisherDomain: "shop.example", SelectionType: "all"},
},
PricingOptions: []adcp.PricingOption{
{PricingOptionID: "sp-cpc", PricingModel: "cpc", FixedPrice: adcp.Ptr(0.50), Currency: "USD"},
},
FormatIDs: []adcp.FormatRef{{AgentURL: agentURL, ID: "product-card"}},
ReportingCapabilities: adcp.ReportingCapabilities{
AvailableMetrics: []string{"impressions", "spend", "clicks", "conversions"},
AvailableReportingFrequencies: []string{"daily"},
ExpectedDelayMinutes: 60,
Timezone: "UTC",
SupportsWebhooks: false,
DateRangeSupport: "date_range",
},
},
}
adcp.AddTool(server, "get_products", "Available products",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.GetProductsRequest) (*mcp.CallToolResult, any, error) {
return adcp.ProductsResponse(&adcp.ProductsData{Products: products, Sandbox: true})
})
5. create_media_buy
adcp.AddTool(server, "create_media_buy", "Create media buy",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.CreateMediaBuyRequest) (*mcp.CallToolResult, any, error) {
id := fmt.Sprintf("mb-%d", counter)
var pkgs []adcp.Package
for i, p := range input.Packages {
pkgs = append(pkgs, adcp.Package{
PackageID: fmt.Sprintf("%s-pkg-%d", id, i+1),
ProductID: p.ProductID, PricingOptionID: p.PricingOptionID, Budget: p.Budget,
CreativeAssignments: p.CreativeAssignments,
})
}
return adcp.MediaBuyResponse(&adcp.CreateMediaBuySuccess{
MediaBuyID: id, Status: "active", Packages: pkgs,
ValidActions: []string{"pause", "cancel", "sync_creatives", "update_packages"},
})
})
6. get_media_buys
adcp.AddTool(server, "get_media_buys", "List media buys",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.GetMediaBuysRequest) (*mcp.CallToolResult, any, error) {
buys := []adcp.MediaBuyData{{
MediaBuyID: "mb-1", Status: "active", Currency: "USD", TotalBudget: 1000,
ValidActions: []string{"pause", "cancel", "sync_creatives", "update_packages"},
Packages: []adcp.PackageStatus{{Package: adcp.Package{PackageID: "mb-1-pkg-1", ProductID: "sponsored-products", Budget: 1000}}},
}}
return adcp.MediaBuysResponse(buys, true)
})
7. list_creative_formats
adcp.AddTool(server, "list_creative_formats", "Available formats",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.ListCreativeFormatsRequest) (*mcp.CallToolResult, any, error) {
return adcp.CreativeFormatsResponse(creativeFormats, true)
})
8. sync_creatives
adcp.AddTool(server, "sync_creatives", "Submit creatives",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.SyncCreativesRequest) (*mcp.CallToolResult, any, error) {
var results []adcp.CreativeResult
for _, c := range input.Creatives {
results = append(results, adcp.CreativeResult{
CreativeID: c.CreativeID, Action: "created", Status: "approved",
})
}
return adcp.SyncCreativesResponse(results, true)
})
9. get_media_buy_delivery
adcp.AddTool(server, "get_media_buy_delivery", "Delivery metrics",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.GetMediaBuyDeliveryRequest) (*mcp.CallToolResult, any, error) {
deliveries := make([]adcp.MediaBuyDelivery, 0)
return adcp.DeliveryResponse(&adcp.DeliveryData{
ReportingPeriod: adcp.ReportingPeriod{Start: start, End: end},
MediaBuyDeliveries: deliveries,
})
})
10. sync_catalogs
adcp.AddTool(server, "sync_catalogs", "Accept product catalog feeds",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.SyncCatalogsRequest) (*mcp.CallToolResult, any, error) {
var results []adcp.CatalogResult
for _, c := range input.Catalogs {
count := len(c.Items)
if count == 0 { count = 10 }
results = append(results, adcp.CatalogResult{
CatalogID: c.CatalogID, Action: "created", ItemCount: count, ItemsApproved: count,
})
}
return adcp.SyncCatalogsResponse(results, true)
})
11. sync_event_sources
adcp.AddTool(server, "sync_event_sources", "Register event tracking",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.SyncEventSourcesRequest) (*mcp.CallToolResult, any, error) {
var results []adcp.EventSourceResult
for _, es := range input.EventSources {
results = append(results, adcp.EventSourceResult{
EventSourceID: es.EventSourceID, Action: "created",
Setup: &adcp.EventSourceSetup{
Snippet: fmt.Sprintf("<script src=\"https://track.example.com/%s.js\"></script>", es.EventSourceID),
Description: "Add this snippet to your checkout page",
},
})
}
return adcp.SyncEventSourcesResponse(results, true)
})
12. log_event
adcp.AddTool(server, "log_event", "Accept conversion events",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.LogEventRequest) (*mcp.CallToolResult, any, error) {
return adcp.LogEventResponse(len(input.Events), len(input.Events), 0.85, true)
})
13. provide_performance_feedback
adcp.AddTool(server, "provide_performance_feedback", "Accept performance metrics",
func(ctx context.Context, req *mcp.CallToolRequest, input adcp.ProvidePerformanceFeedbackRequest) (*mcp.CallToolResult, any, error) {
return adcp.PerformanceFeedbackResponse(true)
})
Compliance Testing
Same pattern as seller — adcp.RegisterTestController(server, store) with ForceAccountStatus, ForceMediaBuyStatus, ForceCreativeStatus, SimulateDelivery, SimulateBudgetSpend.
Complete Skeleton
package main
import (
"context"
"fmt"
"log"
"sync"
"time"
"github.com/adcontextprotocol/adcp-go/adcp"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
const agentURL = "http://localhost:3001/mcp"
type store struct {
mu sync.RWMutex
accounts map[string]*adcp.AccountResult
mediaBuys map[string]*adcp.MediaBuyData
creatives map[string]string
delivery map[string]*deliveryState
catalogs map[string]int
eventSources map[string]bool
}
type deliveryState struct { Impressions, Clicks int; Spend float64 }
var products = []adcp.Product{ }
var creativeFormats = []adcp.CreativeFormat{ }
func createServer(s *store) *mcp.Server {
server := mcp.NewServer(&mcp.Implementation{Name: "my-retail", Version: "1.0.0"}, nil)
return server
}
func main() {
s := &store{accounts: make(map[string]*adcp.AccountResult), mediaBuys: make(map[string]*adcp.MediaBuyData), creatives: make(map[string]string), delivery: make(map[string]*deliveryState), catalogs: make(map[string]int), eventSources: make(map[string]bool)}
log.Fatal(adcp.Serve(func() *mcp.Server { return createServer(s) }))
}
go.mod
module your-retail-media
go 1.25
require (
github.com/adcontextprotocol/adcp-go/adcp v0.0.0
github.com/modelcontextprotocol/go-sdk v1.5.0
)
Then go mod tidy.
Validation
go run main.go &
npx @adcp/client storyboard run http://localhost:3001/mcp media_buy_catalog_creative --json
Common Mistakes
| Mistake | Fix |
|---|
Using mcp.AddTool directly | Use adcp.AddTool |
Missing conversion_tracking in supported_protocols | Storyboard rejects catalog/event tools without it |
Products missing description | Required field |
Missing publisher_properties, format_ids, or reporting_capabilities | Required fields |
sync_catalogs missing item_count | Required field |
log_event missing events_received | Required counter |
log_event missing match_quality | Include match quality score (0.0-1.0) via adcp.LogEventResponse |
sync_event_sources missing setup.snippet | Include Setup with integration snippet on each event source |
sync_governance response key results | Must be accounts |
get_delivery returns null for empty arrays | Use make([]T, 0) |
get_delivery returns null for empty deliveries | Use adcp.DeliveryResponse |
| Uppercase pricing model | Use "cpm", "cpc" not "CPM" |
| No mutex on maps | Use sync.RWMutex |
SDK Reference
| Function | Usage |
|---|
adcp.AddTool(server, name, desc, handler) | Register tool |
adcp.Serve(createAgent) | HTTP server |
adcp.RegisterTestController(server, store) | Test controller |
adcp.CapabilitiesResponse(data) | Capabilities |
adcp.ProductsResponse(data) | Products |
adcp.MediaBuyResponse(*CreateMediaBuySuccess|*CreateMediaBuyError|*CreateMediaBuySubmitted) | Create media buy |
adcp.CreateMediaBuySuccessResponse(data) | Sync create media buy |
adcp.CreateMediaBuyErrorResponse(data) | Create media buy error branch |
adcp.CreateMediaBuySubmittedResponse(taskID, message) | Async create media buy |
adcp.MediaBuysResponse(buys, sandbox) | List media buys |
adcp.DeliveryResponse(data) | Delivery metrics |
adcp.SyncAccountsResponse(accounts, sandbox) | Sync accounts |
adcp.GovernanceResponse(accounts) | Sync governance |
adcp.CreativeFormatsResponse(formats, sandbox) | Creative formats |
adcp.SyncCreativesResponse(creatives, sandbox) | Sync creatives |
adcp.SyncCatalogsResponse(catalogs, sandbox) | Sync catalogs |
adcp.SyncEventSourcesResponse(sources, sandbox) | Event sources |
adcp.LogEventResponse(received, processed, matchQuality, sandbox) | Log events |
adcp.PerformanceFeedbackResponse(sandbox) | Performance feedback |
adcp.Result(data, summary) | Generic response |
adcp.Errorf(code, opts) | Error response |
Input types: adcp.EmptyInput, adcp.SyncAccountsRequest, adcp.SyncGovernanceRequest, adcp.GetProductsRequest, adcp.CreateMediaBuyRequest, adcp.GetMediaBuysRequest, adcp.ListCreativeFormatsRequest, adcp.SyncCreativesRequest, adcp.GetMediaBuyDeliveryRequest, adcp.SyncCatalogsRequest, adcp.SyncEventSourcesRequest, adcp.LogEventRequest, adcp.ProvidePerformanceFeedbackRequest
The skill contains everything you need.
