AdCP Signals Protocol

This skill enables you to execute the AdCP Signals Protocol with signal agents. Use the standard MCP tools (get_signals, activate_signal) exposed by the connected agent.

Overview

The Signals Protocol provides 2 standardized tasks for discovering and activating targeting data:

Typical Workflow

1. •Discover signals: get_signals with a natural language description of targeting needs
2. •Review options: Evaluate signals by coverage, pricing, and deployment status
3. •Activate if needed: activate_signal for signals not yet live on your platform
4. •Use in campaigns: Reference the activation key in your media buy targeting

Task Reference

get_signals

Discover signals based on natural language description, with deployment status across platforms.

Request:

{
  "signal_spec": "High-income households interested in luxury goods",
  "deliver_to": {
    "deployments": [
      {
        "type": "platform",
        "platform": "the-trade-desk",
        "account": "agency-123"
      }
    ],
    "countries": ["US"]
  },
  "filters": {
    "max_cpm": 5.0,
    "catalog_types": ["marketplace"]
  },
  "max_results": 5
}

Key fields:

• •signal_spec (string, required): Natural language description of desired signals
• •deliver_to (object, required): Where signals will be used
  • •deployments (array): Target platforms/agents with type, platform/agent_url, and optional account
  • •countries (array): ISO country codes where signals will be used
• •filters (object, optional): Filter by catalog_types, data_providers, max_cpm, min_coverage_percentage
• •max_results (number, optional): Limit number of results

Deployment types:

// DSP platform
{ "type": "platform", "platform": "the-trade-desk", "account": "agency-123" }

// Sales agent
{ "type": "agent", "agent_url": "https://salesagent.example.com" }

Response contains:

• •signals: Array of matching signals with:
  • •signal_agent_segment_id: Use this in activate_signal
  • •name, description: Human-readable signal info
  • •data_provider: Source of the signal data
  • •coverage_percentage: Reach relative to agent's population
  • •deployments: Status per platform with is_live, activation_key, estimated_activation_duration_minutes
  • •pricing: CPM and currency

activate_signal

Activate a signal for use on a specific platform or agent.

Request:

{
  "signal_agent_segment_id": "luxury_auto_intenders",
  "deployments": [
    {
      "type": "platform",
      "platform": "the-trade-desk",
      "account": "agency-123-ttd"
    }
  ]
}

Key fields:

• •signal_agent_segment_id (string, required): From get_signals response
• •deployments (array, required): Target deployment(s) with type, platform/agent_url, and optional account

Response contains:

• •deployments: Array with activation results per target
  • •activation_key: The key to use for targeting (segment ID or key-value pair)
  • •deployed_at: ISO timestamp when activation completed
  • •estimated_activation_duration_minutes: Time remaining if async
• •errors: Any warnings or errors encountered

Key Concepts

Deployment Targets

Signals can be activated on two types of targets:

DSP Platforms:

{
  "type": "platform",
  "platform": "the-trade-desk",
  "account": "agency-123"
}

Sales Agents:

{
  "type": "agent",
  "agent_url": "https://wonderstruck.salesagents.com"
}

Activation Keys

When signals are live, the response includes an activation key for targeting:

Segment ID format (typical for DSPs):

{
  "type": "segment_id",
  "segment_id": "ttd_segment_12345"
}

Key-Value format (typical for sales agents):

{
  "type": "key_value",
  "key": "audience_segment",
  "value": "luxury_auto_intenders"
}

Signal Types

• •marketplace: Licensed from data providers (CPM pricing)
• •custom: Built for specific principal accounts
• •owned: Private signals from your own data (no cost)

Coverage Percentage

Indicates signal reach relative to the agent's population:

• •99%: Very broad signal (matches most identifiers)
• •50%: Medium signal
• •1%: Very niche signal

Asynchronous Operations

Signal activation may take time. Check the response:

• •is_live: true + activation_key: Ready to use immediately
• •is_live: false + estimated_activation_duration_minutes: Activation in progress

Poll or use webhooks to check completion status.

Error Handling

Common error codes:

• •SIGNAL_AGENT_SEGMENT_NOT_FOUND: Invalid signal_agent_segment_id
• •ACTIVATION_FAILED: Could not activate signal
• •ALREADY_ACTIVATED: Signal already active on target
• •DEPLOYMENT_UNAUTHORIZED: Not authorized for platform/account
• •AGENT_NOT_FOUND: Private agent not visible to this principal
• •AGENT_ACCESS_DENIED: Not authorized for this signal agent

Error responses include:

{
  "errors": [
    {
      "code": "DEPLOYMENT_UNAUTHORIZED",
      "message": "Account not authorized for this data provider",
      "field": "deployment.account",
      "suggestion": "Contact your account manager to enable access"
    }
  ]
}