get_adcp_capabilities

Discovery Flow:
1. Browse the agent's tool list (MCP), or find and activate the versioned AdCP profile in AgentCard.capabilities.extensions[] (A2A)
2. See the get_adcp_capabilities tool/skill → Runtime AdCP discovery is available
3. Call get_adcp_capabilities → Get version, protocols, features, capabilities
4. Proceed based on returned capabilities

Version Negotiation Flow:
1. Buyer calls get_adcp_capabilities with adcp_major_version: 2
2. Seller checks 2 against its major_versions: [2, 3]
3. Version is supported → seller returns capabilities for v2
4. Buyer includes adcp_major_version: 2 on all subsequent requests

{
  "adcp": {
    "major_versions": [3],
    "idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
  }
}

{
  "adcp": {
    "major_versions": [3],
    "idempotency": { "supported": false }
  }
}

{
  "adcp": {
    "major_versions": [3],
    "idempotency": { "supported": true, "replay_ttl_seconds": 86400 },
    "capability_changes": {
      "capabilities_version": "rev_20260702_091455",
      "last_modified": "2026-07-02T09:14:55Z",
      "cache_ttl_seconds": 3600,
      "notifications": {
        "supported": true,
        "registration_task": "sync_agent_notification_configs",
        "event_types": ["capabilities.changed"],
        "coalescence_window_seconds": 300
      }
    }
  }
}

{
  "adcp": {
    "major_versions": [3],
    "idempotency": { "supported": true, "replay_ttl_seconds": 86400 },
    "governance_enforcement": {
      "tasks": [
        {
          "task": "create_media_buy",
          "modes": ["signed_context", "online_execution_check"]
        },
        { "task": "activate_signal", "modes": ["signed_context"] }
      ]
    }
  }
}

{
  "adcp": {
    "major_versions": [3],
    "idempotency": { "supported": true, "replay_ttl_seconds": 86400 },
    "attestations": {
      "accepted_claim_types": [
        "https://claims.example/audience/methodology-reviewed",
        "https://adcontextprotocol.org/claims/rights/grant"
      ],
      "accepted_proof_formats": [
        "https://www.w3.org/TR/vc-jose-cose/"
      ],
      "supported_delivery_methods": [
        "issuer_credential_id",
        "embedded"
      ],
      "accepted_issuers": [
        {
          "issuer": {
            "type": "origin",
            "origin": "https://credentials.example"
          },
          "claim_types": ["https://claims.example/audience/methodology-reviewed"],
          "resolvers": [
            {
              "resolver_id": "primary",
              "url": "https://resolver.credentials.example/v1/credentials",
              "authentication": "evaluator_managed"
            }
          ]
        },
        {
          "issuer": {
            "type": "brand",
            "brand": { "domain": "novabrands.example", "brand_id": "nova_talent" }
          },
          "claim_types": ["https://adcontextprotocol.org/claims/rights/grant"],
          "proof_formats": ["https://www.w3.org/TR/vc-jose-cose/"],
          "resolvers": [
            {
              "resolver_id": "rights-primary",
              "url": "https://rights.novabrands.example/credentials",
              "authentication": "evaluator_managed"
            }
          ]
        }
      ],
      "accepted_verifiers": [
        {
          "agent_url": "https://verification.example/adcp"
        }
      ],
      "max_embedded_credential_bytes": 262144
    }
  }
}

{
  "supported_protocols": ["media_buy", "creative"]
}

{
  "specialisms": ["sales-guaranteed", "creative-template"]
}

{
  "oauth": {
    "supported": true
  }
}

{
  "account": {
    "supported_billing": ["operator", "agent"],
    "supported_account_currency_modes": ["fixed", "per_media_buy"],
    "timezone": {
      "mode": "account_fixed",
      "account_selection": "buyer_selected",
      "supported_timezones": ["America/New_York", "Europe/London", "UTC"]
    },
    "notifications": {
      "supported": true,
      "registration_task": "sync_accounts",
      "read_task": "list_accounts",
      "event_types": ["account.status_changed"],
      "supports_webhook_activity": true
    }
  }
}

{
  "account": {
    "supported_billing": ["operator", "agent"],
    "identity_updates": {
      "supported": true,
      "supported_changes": ["operator_unit_name", "operator_unit", "operator"]
    }
  }
}

{
  "media_buy": {
    "budget_capping": {
      "supported_scopes": ["media_buy", "package"],
      "supported_periods": ["day"],
      "timezone_basis": "account",
      "buyer_timezone_override": true
    }
  }
}

{
  "media_buy": {
    "supported_indicator_types": [
      "creative_fatigue",
      "creative_quality_opportunity",
      "creative_diversity_low",
      "audience_saturation",
      "inventory_shortfall_forecast",
      "pacing_risk",
      "budget_constrained"
    ],
    "relationship_notifications": {
      "supported": true,
      "registration_task": "sync_accounts",
      "event_types": ["indicators.changed", "creative.assignment_changed"],
      "repair_tasks": ["get_media_buys"],
      "projection_tasks": ["list_creatives"],
      "supports_webhook_activity": true
    }
  },
  "webhook_signing": {
    "supported": true,
    "profile": "adcp/webhook-signing/v1",
    "algorithms": ["ed25519"],
    "legacy_hmac_fallback": false
  }
}

{
  "features": {
    "bidding_policy": {
      "media_buy": {
        "fixed": {
          "modes": ["max_bid", "cost_per"],
          "cost_per_strengths": ["cap", "target"],
          "supported_combinations": [
            {
              "kind": "max_bid_with_cost_per",
              "cost_per_strengths": ["cap"]
            }
          ]
        }
      },
      "package": {
        "seller_optimized": {
          "modes": ["automatic", "cost_per"],
          "cost_per_strengths": ["cap"]
        }
      }
    }
  }
}

{
  "content_standards": {
    "supports_local_evaluation": true,
    "supported_channels": ["display", "olv", "podcast"],
    "supports_webhook_delivery": true
  }
}

{
  "us_zip": true,
  "us_zip_plus_four": true,
  "US": ["zip", "zip_plus_four"],
  "GB": ["outward", "full"],
  "CA": ["fsa", "full"],
  "ZA": ["postal_code"]
}

{
  "geonames": {
    "countries": {
      "US": ["city", "county"],
      "NL": ["city", "municipality"],
      "GB": ["city", "post_town"]
    },
    "catalog": {
      "source": "https://seller.example/data-sources/geonames-mirror",
      "current_version": "2026-05",
      "supported_versions": ["2026-05", "2026-04"],
      "resolver": {
        "url": "https://seller.example/adcp/geo/resolve/geonames",
        "auth": "seller_credentials",
        "protocol": "adcp_geo_place_resolver_v1"
      }
    }
  },
  "https://seller.example/geo/catalogs/places": {
    "countries": {
      "NL": ["city"]
    },
    "catalog": {
      "current_version": "2026-q2",
      "supported_versions": ["2026-q2"],
      "resolver": {
        "url": "https://seller.example/adcp/geo/resolve/private",
        "auth": "seller_credentials",
        "protocol": "adcp_geo_place_resolver_v1"
      }
    }
  }
}

GET https://seller.example/adcp/geo/resolve/geonames?q=Springfield&country=US&subdivision=US-IL&place_type=city&system_version=2026-05&limit=20

{
  "request": {
    "q": "Springfield",
    "country": "US",
    "subdivision": "US-IL",
    "place_type": "city",
    "system_version": "2026-05",
    "limit": 20
  },
  "system": "geonames",
  "system_version": "2026-05",
  "matches": [{
    "value": "4250542",
    "country": "US",
    "subdivision": "US-IL",
    "place_type": "city",
    "label": "Springfield",
    "canonical_name": "Springfield, Illinois, United States",
    "parent_labels": ["Illinois", "United States"],
    "status": "active"
  }]
}

{
  "media_buy": {
    "rights_attestations": {
      "requirement": "required"
    }
  }
}

{
  "media_buy": {
    "audience_evidence": {
      "supported_requirement_modes": ["required", "preferred"],
      "supported_presence_modes": ["required", "when_available"],
      "supports_attestation_evaluation": true
    }
  }
}

{
  "$schema": "/schemas/3.2.0-beta.0/protocol/get-adcp-capabilities-response.json",
  "status": "completed",
  "adcp": {
    "major_versions": [3],
    "idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
  },
  "supported_protocols": ["governance"],
  "governance": {
    "property_features": [
      {
        "feature_id": "mfa_score",
        "type": "quantitative",
        "range": { "min": 0, "max": 100 },
        "description": "Made For Advertising detection (0=quality content, 100=likely MFA)",
        "methodology_url": "https://vendor.example.com/methodology/mfa"
      },
      {
        "feature_id": "coppa_certified",
        "type": "binary",
        "description": "COPPA compliance certification"
      },
      {
        "feature_id": "registry:uk_hfss",
        "type": "binary",
        "description": "UK HFSS advertising restrictions compliance"
      },
      {
        "feature_id": "carbon_score",
        "type": "quantitative",
        "range": { "min": 0, "max": 100 },
        "description": "Carbon footprint sustainability score",
        "methodology_url": "https://vendor.example.com/methodology/carbon-score"
      }
    ],
    "creative_features": [
      {
        "feature_id": "registry:eu_ai_act_article_50",
        "type": "binary",
        "description": "EU AI Act Article 50 — AI-generated content disclosure"
      },
      {
        "feature_id": "registry:ca_sb_942",
        "type": "binary",
        "description": "California SB 942 — AI transparency compliance"
      },
      {
        "feature_id": "auto_redirect",
        "type": "binary",
        "description": "Detects auto-redirect behavior in creative code"
      },
      {
        "feature_id": "credential_harvest",
        "type": "binary",
        "description": "Detects credential harvesting patterns"
      }
    ],
    "content_standards": {
      "supported": true,
      "calibration_formats": ["text", "image", "video"]
    },
    "policy_registry": {
      "supported": true,
      "domains": ["campaign", "property", "creative", "content_standards"]
    }
  }
}

{
  "supported_protocols": ["measurement"],
  "experimental_features": ["measurement.gateway"],
  "measurement_gateway": {
    "delivery_task": "get_media_buy_delivery",
    "feedback_task": "provide_performance_feedback"
  }
}

{
  "webhook_signing": {
    "supported": true,
    "profile": "adcp/webhook-signing/v1",
    "algorithms": ["ed25519", "ecdsa-p256-sha256"],
    "legacy_hmac_fallback": false
  }
}

{
  "extensions_supported": ["iab_tcf", "iab_gpp", "acmecorp"]
}

{
  "experimental_features": [
    "brand.rights_lifecycle",
    "measurement.core",
    "trusted_match.core"
  ]
}

{
  "wholesale_feed_versioning": {
    "supported": true,
    "pricing_version_separate": true,
    "cache_scope_account": true
  }
}

{
  "wholesale_feed_webhooks": {
    "supported": true,
    "event_types": [
      "product.created",
      "product.updated",
      "product.priced",
      "product.removed",
      "signal.created",
      "signal.updated",
      "signal.priced",
      "signal.removed",
      "wholesale_feed.bulk_change"
    ]
  }
}

import { AdcpClient } from "@adcp/sdk";

const client = new AdcpClient({ baseUrl: "https://seller.example.com/mcp" });

// Get seller capabilities
const result = await client.getAdcpCapabilities({});

if (result.errors) {
  throw new Error(`Request failed: ${result.errors[0].message}`);
}

// Check protocol support
console.log(`AdCP versions: ${result.adcp.major_versions.join(", ")}`);
console.log(`Supported protocols: ${result.supported_protocols.join(", ")}`);

// Check media-buy capabilities
if (result.supported_protocols.includes("media_buy")) {
  const mediaBuy = result.media_buy;

  // Check content standards support (object presence = signal)
  if (mediaBuy.content_standards) {
    console.log("Content standards supported");
  }

  // Check AXE integrations (legacy — new integrations use TMP via trusted_match on products)
  if (
    mediaBuy.execution?.axe_integrations?.includes("https://axe.example.com")
  ) {
    console.log("AXE integration available");
  }

  // Check geo targeting (normalize native country keys and deprecated aliases)
  const postalSupport = mediaBuy.execution?.targeting?.geo_postal_areas;
  if (postalSupport?.US?.includes("zip") || postalSupport?.us_zip === true) {
    console.log("US ZIP code targeting supported");
  }

  // Portfolio overview
  console.log(`Publishers: ${mediaBuy.portfolio.publisher_domains.length}`);
  console.log(`Channels: ${mediaBuy.portfolio.primary_channels?.join(", ")}`);
}

const caps = await client.getAdcpCapabilities({});

const sellsMedia = caps.supported_protocols.includes("media_buy");
const managesCreatives = caps.supported_protocols.includes("creative");

if (sellsMedia && managesCreatives) {
  // Single agent handles both protocols — no need to discover a separate service
  const formats = await client.listCreativeFormats({});
  const delivery = await client.getCreativeDelivery({
    media_buy_ids: ["mb_12345"],
  });
}

// Find sellers that support specific requirements
async function findCompatibleSellers(sellers, requirements) {
  const compatible = [];

  for (const sellerUrl of sellers) {
    const client = new AdcpClient({ baseUrl: sellerUrl });
    const caps = await client.getAdcpCapabilities({});

    if (caps.errors) continue;

    // Must support media_buy protocol
    if (!caps.supported_protocols.includes("media_buy")) continue;

    const mediaBuy = caps.media_buy;

    // Check AXE integration requirement (legacy — new integrations use TMP)
    if (requirements.axeIntegration) {
      if (
        !mediaBuy.execution?.axe_integrations?.includes(
          requirements.axeIntegration
        )
      ) {
        continue;
      }
    }

    // Check geo targeting requirement
    if (requirements.postalCodeTargeting) {
      const postalSupport = mediaBuy.execution?.targeting?.geo_postal_areas;
      if (
        !(postalSupport?.US?.includes("zip") || postalSupport?.us_zip === true)
      ) {
        continue;
      }
    }

    // Check content standards requirement (object presence = signal)
    if (requirements.contentStandards) {
      if (!mediaBuy.content_standards) {
        continue;
      }
    }

    compatible.push({ url: sellerUrl, capabilities: caps });
  }

  return compatible;
}

// Usage
const sellers = await findCompatibleSellers(
  ["https://seller1.com/mcp", "https://seller2.com/mcp"],
  {
    axeIntegration: "https://axe.example.com",
    postalCodeTargeting: true,
    contentStandards: true,
  }
);

// First, check capabilities
const caps = await client.getAdcpCapabilities({});

if (!caps.supported_protocols.includes("media_buy")) {
  throw new Error("Seller does not support media_buy protocol");
}

const mediaBuy = caps.media_buy;
const postalSupport = mediaBuy.execution?.targeting?.geo_postal_areas;

// Filter products to sellers with specific geo targeting capabilities
const products = await client.getProducts({
  idempotency_key: '550e8400-e29b-41d4-a716-446655442047',
  buying_mode: 'brief',
  brief: "Premium video inventory in US for ZIP-targeted campaign",
  filters: { channels: ['olv', 'ctv'] },
  targeting_overlay: { geo_countries: ['US'] },
  required_overlay_support: {
    geo_postal_areas: { US: ['zip'] }
  }
});

// Then, create media buy with fine-grained targeting
// (if seller supports postal areas, we can target specific ZIP codes)
const buy = await client.createMediaBuy({
  brand: { domain: 'mybrand.com' },
  packages: [{
    product_id: products.products[0].product_id,
    pricing_option_id: products.products[0].pricing_options[0].id,
    budget: 10000,
    // The configured product already represents US targeting. Add the ZIP
    // selection the buyer deferred during discovery.
    targeting_overlay: {
      geo_countries: ['US'],
      // Only specify ZIP targeting if seller supports it
      ...((postalSupport?.US?.includes('zip') || postalSupport?.us_zip === true) && {
        geo_postal_areas: [{
          country: 'US',
          system: 'zip',
          values: ['10001', '10002', '10003', '10004', '10005']
        }]
      })
    }
  }],
  start_time: { type: 'asap' },
  end_time: '2025-03-01T00:00:00Z'
});

// Find radio products in specific DMAs
const radioProducts = await client.getProducts({
  idempotency_key: '550e8400-e29b-41d4-a716-446655442048',
  buying_mode: 'brief',
  brief: "Radio inventory in NYC and LA markets",
  filters: {
    channels: ["radio"],
    // Coverage filter: products must cover these metros
    metros: [
      { system: "nielsen_dma", code: "501" }, // NYC
      { system: "nielsen_dma", code: "803" }, // LA
    ],
  },
});

// For local inventory, targeting_overlay is optional -
// the product's coverage IS the geography
const buy = await client.createMediaBuy({
  brand: { domain: "mybrand.com" },
  packages: [
    {
      product_id: radioProducts.products[0].product_id,
      pricing_option_id: radioProducts.products[0].pricing_options[0].id,
      budget: 5000,
      // No targeting_overlay needed - product covers NYC DMA
    },
  ],
  start_time: { type: "asap" },
  end_time: "2025-03-01T00:00:00Z",
});

{
  "$schema": "/schemas/3.2.0-beta.0/protocol/get-adcp-capabilities-response.json",
  "status": "completed",
  "adcp": {
    "major_versions": [3],
    "idempotency": { "supported": true, "replay_ttl_seconds": 86400 }
  },
  "supported_protocols": ["media_buy"],
  "account": {
    "require_operator_auth": false,
    "supported_billing": ["operator", "agent"],
    "supported_account_currency_modes": ["fixed", "per_media_buy"],
    "timezone": { "mode": "seller_fixed", "fixed_timezone": "UTC" }
  },
  "media_buy": {
    "creative_approval_mode": "auto_approve",
    "features": {
      "inline_creative_management": true,
      "property_list_filtering": true,
      "seller_optimized_budget": true,
      "bidding_policy": {
        "media_buy": {
          "fixed": {
            "modes": ["max_bid", "cost_per"],
            "cost_per_strengths": ["cap", "target"],
            "supported_combinations": [
              {
                "kind": "max_bid_with_cost_per",
                "cost_per_strengths": ["cap"]
              }
            ]
          },
          "seller_optimized": {
            "modes": ["cost_per"],
            "cost_per_strengths": ["cap"]
          }
        },
        "package": {
          "fixed": {
            "modes": ["automatic", "bid_amount", "cost_per"],
            "cost_per_strengths": ["cap"]
          },
          "seller_optimized": {
            "modes": ["automatic"]
          }
        }
      }
    },
    "execution": {
      "axe_integrations": ["https://axe.example.com"],
      "creative_specs": {
        "vast_versions": ["4.0", "4.1", "4.2", "4.3"],
        "mraid_versions": ["3.0"],
        "vpaid": false,
        "simid": true
      },
      "targeting": {
        "geo_countries": true,
        "geo_regions": true,
        "geo_metros": {
          "nielsen_dma": true
        },
        "geo_postal_areas": {
          "us_zip": true,
          "us_zip_plus_four": true,
          "US": ["zip", "zip_plus_four"],
          "GB": ["outward", "full"],
          "CA": ["fsa", "full"],
          "ZA": ["postal_code"]
        },
        "geo_places": {
          "geonames": {
            "countries": {
              "US": ["city", "county"],
              "NL": ["city", "municipality"],
              "GB": ["city", "post_town"]
            },
            "catalog": {
              "source": "https://seller.example/data-sources/geonames-mirror",
              "current_version": "2026-05",
              "supported_versions": ["2026-05", "2026-04"],
              "resolver": {
                "url": "https://seller.example/adcp/geo/resolve/geonames",
                "auth": "seller_credentials",
                "protocol": "adcp_geo_place_resolver_v1"
              }
            }
          },
          "https://seller.example/geo/catalogs/places": {
            "countries": {
              "NL": ["city"]
            },
            "catalog": {
              "current_version": "2026-q2",
              "supported_versions": ["2026-q2"],
              "resolver": {
                "url": "https://seller.example/adcp/geo/resolve/private",
                "auth": "seller_credentials",
                "protocol": "adcp_geo_place_resolver_v1"
              }
            }
          }
        },
        "language": {
          "supported": true,
          "supported_languages": ["en", "fr-CA", "es"]
        },
        "keyword_targets": {
          "supported_match_types": ["broad", "phrase", "exact"]
        },
        "negative_keywords": {
          "supported_match_types": ["broad", "exact"]
        }
      }
    },
    "content_standards": {
      "supports_local_evaluation": true,
      "supported_channels": ["display", "olv"],
      "supports_webhook_delivery": false
    },
    "audience_targeting": {
      "supported_identifier_types": ["hashed_email", "hashed_phone"],
      "supports_platform_customer_id": false,
      "supported_uid_types": ["uid2", "rampid"],
      "minimum_audience_size": 500,
      "matching_latency_hours": { "min": 1, "max": 24 }
    },
    "conversion_tracking": {
      "multi_source_event_dedup": false,
      "supported_event_types": [
        "purchase",
        "lead",
        "add_to_cart",
        "view_content"
      ],
      "supported_action_sources": ["website", "app"],
      "attribution_windows": [
        {
          "post_click": [
            { "interval": 7, "unit": "days" },
            { "interval": 28, "unit": "days" }
          ],
          "post_view": [
            { "interval": 1, "unit": "days" },
            { "interval": 7, "unit": "days" }
          ]
        }
      ]
    },
    "portfolio": {
      "publisher_domains": ["example.com", "news.example.com"],
      "primary_channels": ["display", "olv"],
      "primary_countries": ["US", "CA"]
    }
  },
  "extensions_supported": ["acmecorp"],
  "last_updated": "2025-01-23T10:00:00Z"
}

{
  "$schema": "/schemas/3.2.0-beta.0/protocol/get-adcp-capabilities-response.json",
  "status": "completed",
  "adcp": {
    "major_versions": [3],
    "idempotency": { "supported": true, "replay_ttl_seconds": 86400 },
    "capability_changes": {
      "capabilities_version": "rev_20260702_091455",
      "last_modified": "2026-07-02T09:14:55Z",
      "cache_ttl_seconds": 3600,
      "notifications": {
        "supported": true,
        "registration_task": "sync_agent_notification_configs",
        "event_types": ["capabilities.changed"]
      }
    }
  },
  "supported_protocols": ["media_buy", "creative"],
  "account": {
    "require_operator_auth": false,
    "supported_billing": ["operator"],
    "supported_account_currency_modes": ["fixed"],
    "timezone": { "mode": "seller_fixed", "fixed_timezone": "UTC" }
  },
  "media_buy": {
    "creative_approval_mode": "require_human",
    "features": {
      "inline_creative_management": true
    },
    "portfolio": {
      "publisher_domains": ["news.example.com"],
      "primary_channels": ["display", "olv"]
    }
  },
  "creative": {
    "has_creative_library": true,
    "supports_generation": true,
    "supports_transformation": false,
    "supports_compliance": false,
    "bills_through_adcp": true,
    "supported_formats": [
      {
        "capability_id": "display_image_generator",
        "operations": ["build", "validate", "preview"],
        "format": {
          "format_kind": "image",
          "params": { "width": 300, "height": 250 }
        }
      }
    ]
  }
}