Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,27 @@ Visit [adcontextprotocol.github.io](https://adcontextprotocol.github.io) for ful

## What is Ad Context Protocol?

Ad Context Protocol (AdCP) is an open standard that enables AI assistants to interact with advertising platforms through natural language. Built on the Model Context Protocol (MCP), AdCP allows marketers to discover audiences, curate inventory, and execute campaigns using conversational AI.
Ad Context Protocol (AdCP) is an open standard that enables AI assistants to interact with advertising platforms through natural language. Built on the Model Context Protocol (MCP), AdCP allows marketers to discover signals (audiences, contextual, geographical, temporal data), curate inventory, and execute campaigns using conversational AI.

### Quick Example

Instead of navigating complex interfaces:

> "Find audiences of premium sports enthusiasts who would be interested in high-end running shoes, and activate them on Scope3."
> "Find audience signals of premium sports enthusiasts who would be interested in high-end running shoes, and activate them on Scope3."

The AI assistant handles:
- Audience discovery across platforms
- Signal discovery across platforms
- Transparent pricing comparison
- Direct activation on decisioning platforms

## Available Protocols

### 🎯 Audience Activation Protocol - RFC/v0.1
Discover and activate marketing audiences using natural language.
### 🎯 Signals Activation Protocol - RFC/v0.1
Discover and activate data signals using natural language.

- **Natural Language Discovery**: "High-income millennials interested in sustainable fashion"
- **Natural Language Discovery**: "High-income millennials interested in sustainable fashion" (audience signal)
- **Contextual Signals**: "Premium automotive content with high viewability"
- **Multi-Dimensional**: Combine geographical, temporal, and behavioral signals
- **Multi-Platform Activation**: Deploy across DSPs and data platforms
- **Transparent Pricing**: CPM and revenue share models
- **Real-time Status**: Track activation and deployment progress
Expand All @@ -43,7 +45,7 @@ Execute and optimize media buys programmatically across platforms.

Implement AdCP to enable AI-powered workflows for your customers:

1. **Review the Specification**: [Audience Protocol](https://adcontextprotocol.github.io/docs/audience/specification)
1. **Review the Specification**: [Signals Protocol](https://adcontextprotocol.github.io/docs/signals/specification)
2. **Implement MCP Server**: Check out the [reference implementations](#reference-implementations)
3. **Test Your Implementation**: Use the validation test suite

Expand All @@ -60,7 +62,7 @@ Use AdCP-enabled platforms with your AI assistant:
```
adcontextprotocol/
├── docs/ # Documentation source files
│ ├── audience/ # Audience protocol docs
│ ├── signals/ # Signals protocol docs
│ ├── curation/ # Curation protocol (coming soon)
│ ├── media-buy/ # Media Buy protocol docs
│ └── reference/ # API reference
Expand Down Expand Up @@ -91,15 +93,15 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## Reference Implementations

- [Audience Agent](https://github.com/adcontextprotocol/audience-agent)
- [Signals Agent](https://github.com/adcontextprotocol/signals-agent)
- [Sales Agent](https://github.com/adcontextprotocol/salesagent)

## Platform Implementations

### Current Support

- **Reference Implementation**: Complete MCP server example
- **Scope3**: Full Audience Activation Protocol support
- **Scope3**: Full Signals Activation Protocol support
- **More Coming**: Additional platforms implementing Q1 2025


Expand Down Expand Up @@ -138,7 +140,7 @@ The Ad Context Protocol specifications are licensed under [Apache 2.0](./LICENSE
## Links

- **Website**: [adcontextprotocol.github.io](https://adcontextprotocol.github.io)
- **Specifications**: [Audience Protocol RFC](./audience-protocol-v1.md)
- **Specifications**: [Signals Protocol RFC](./signals-protocol-v1.md)
- **Discussions**: [GitHub Discussions](https://github.com/adcontextprotocol/adcp/discussions)
- **Issues**: [Report Issues](https://github.com/adcontextprotocol/adcp/issues)

Expand Down
40 changes: 20 additions & 20 deletions docs/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,11 +50,11 @@ Platforms that evaluate sellers and audiences, and execute buying strategies:
- **Function**: Strategy execution, seller evaluation, optimization
- **Integration**: Uses MCP to communicate with both Audience and Sales Agents

#### Audience Agent (Right, Top)
#### Signal Agent (Right, Top)
MCP servers that provide:
- **Audience Discovery**: Finding relevant audiences using natural language
- **Audience Activation**: Pushing audiences to decisioning platforms
- **Integration**: Connects audience platforms to orchestration via MCP
- **Signal Discovery**: Finding relevant signals (audiences, contextual, geographical, temporal) using natural language
- **Signal Activation**: Pushing signals to decisioning platforms
- **Integration**: Connects signal platforms to orchestration via MCP

#### Sales Agent (Right, Bottom)
MCP servers that provide:
Expand All @@ -81,38 +81,38 @@ The technical infrastructure that:

Each AdCP protocol operates within this ecosystem:

### 🎯 Audience Activation Protocol
- **Scope**: Works with **audience platforms** to discover and activate audiences directly on **decisioning platforms**
- **Integration**: Direct integration between audience agents and decisioning platforms (DSPs, injective platforms)
- **Workflow**: Find audiences → Direct activation on target platform → Ready for campaign use
### 🎯 Signals Activation Protocol
- **Scope**: Works with **signal platforms** to discover and activate signals directly on **decisioning platforms**
- **Integration**: Direct integration between signal agents and decisioning platforms (DSPs, injective platforms)
- **Workflow**: Find signals → Direct activation on target platform → Ready for campaign use

### 📍 Curation Protocol (Coming Q2 2025)
- **Scope**: Works with **decisioning platforms** and **supply-side platforms**
- **Integration**: Curates inventory that will be targeted with activated audiences
- **Workflow**: Define requirements → Find inventory → Package with audiences
- **Integration**: Curates inventory that will be targeted with activated signals
- **Workflow**: Define requirements → Find inventory → Package with signals

### 💰 Media Buy Protocol
- **Scope**: Works primarily with **decisioning platforms** (DSPs, injective platforms)
- **Integration**: Executes campaigns using curated inventory and activated audiences
- **Integration**: Executes campaigns using curated inventory and activated signals
- **Workflow**: Set objectives → Execute buys → Optimize performance

## Quick Example

Instead of navigating multiple platforms, you can now say:

> "Find audiences of premium sports enthusiasts who would be interested in high-end running shoes, and activate them on Scope3."
> "Find audience signals of premium sports enthusiasts who would be interested in high-end running shoes, and activate them on Scope3."

The AI assistant will:
1. Search for relevant audiences across connected platforms
1. Search for relevant signals across connected platforms
2. Show you options with transparent pricing
3. Activate your chosen audiences for use on decisioning platforms
3. Activate your chosen signals for use on decisioning platforms

## Available Protocols

### 🎯 [Audience Activation Protocol](./audience/overview)
### 🎯 [Signals Activation Protocol](./signals/overview)
**Status**: RFC/v0.1

Discover and activate marketing audiences using natural language.
Discover and activate data signals (audiences, contextual, geographical, temporal) using natural language.

### 📍 Curation Protocol
**Status**: Coming Q2 2025
Expand All @@ -126,14 +126,14 @@ Execute and optimize media buys programmatically.

## Reference Implementations

- [Audience Agent](https://github.com/adcontextprotocol/audience-agent)
- [Signals Agent](https://github.com/adcontextprotocol/signals-agent)
- [Sales Agent](https://github.com/adcontextprotocol/salesagent)

## For Platform Providers

If you operate an audience platform, DSP, or ad tech solution:
If you operate a signal platform, DSP, or ad tech solution:

1. [Review the Protocol Specifications](./audience/specification)
1. [Review the Protocol Specifications](./signals/specification)

## For Advertisers & Agencies

Expand All @@ -145,7 +145,7 @@ If you want to use AdCP with your AI assistant:

## Next Steps

- **Platform Providers**: Start with the [Audience Protocol Specification](./audience/specification)
- **Platform Providers**: Start with the [Signals Protocol Specification](./signals/specification)
- **Everyone**: Join the [community discussion](https://github.com/adcontextprotocol/adcp/discussions)

## Need Help?
Expand Down
40 changes: 20 additions & 20 deletions docs/reference/error-codes.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,8 @@ Account lacks required permissions for the operation.
"code": "INSUFFICIENT_PERMISSIONS",
"message": "Account does not have activation permissions",
"details": {
"required_permission": "activate_audience",
"account_permissions": ["get_audiences", "check_audience_status"]
"required_permission": "activate_signal",
"account_permissions": ["get_signals", "check_signal_status"]
}
}
}
Expand All @@ -96,7 +96,7 @@ Required request parameter is missing.
"success": false,
"error": {
"code": "MISSING_REQUIRED_FIELD",
"message": "prompt is required for audience discovery",
"message": "prompt is required for signal discovery",
"details": {
"field": "prompt",
"provided_fields": ["platform", "max_results"]
Expand Down Expand Up @@ -163,24 +163,24 @@ Specified segment ID doesn't exist or is no longer available.
"message": "Segment ID not found or has expired",
"details": {
"segment_id": "seg_invalid_123",
"suggestion": "Use get_audiences to find current segment IDs"
"suggestion": "Use get_signals to find current segment IDs"
}
}
}
```

**Resolution**: Use current segment ID from recent `get_audiences` response.
**Resolution**: Use current segment ID from recent `get_signals` response.

### AUDIENCE_UNAVAILABLE
Audience exists but is not available for the requested platform/seat.
### SIGNAL_UNAVAILABLE
Signal exists but is not available for the requested platform/seat.

**Example**:
```json
{
"success": false,
"error": {
"code": "AUDIENCE_UNAVAILABLE",
"message": "Audience not available for the specified platform",
"code": "SIGNAL_UNAVAILABLE",
"message": "Signal not available for the specified platform",
"details": {
"segment_id": "seg_12345",
"requested_platform": "unavailable_platform",
Expand Down Expand Up @@ -237,15 +237,15 @@ Account cannot access specified seat.
## Operation Errors

### ALREADY_ACTIVATED
Audience is already active for the specified platform/seat.
Signal is already active for the specified platform/seat.

**Example**:
```json
{
"success": false,
"error": {
"code": "ALREADY_ACTIVATED",
"message": "Audience already activated for this platform and seat",
"message": "Signal already activated for this platform and seat",
"details": {
"segment_id": "seg_12345",
"platform": "scope3",
Expand All @@ -257,18 +257,18 @@ Audience is already active for the specified platform/seat.
}
```

**Resolution**: Use existing activation or check status with `check_audience_status`.
**Resolution**: Use existing activation or check status with `check_signal_status`.

### ACTIVATION_FAILED
Audience activation process failed.
Signal activation process failed.

**Example**:
```json
{
"success": false,
"error": {
"code": "ACTIVATION_FAILED",
"message": "Failed to activate audience due to provider error",
"message": "Failed to activate signal due to provider error",
"details": {
"segment_id": "seg_12345",
"provider_error": "Segment temporarily unavailable",
Expand All @@ -282,15 +282,15 @@ Audience activation process failed.
**Resolution**: Wait and retry, or contact support if persistent.

### INVALID_PRICING_MODEL
Requested pricing model is not available for this audience.
Requested pricing model is not available for this signal.

**Example**:
```json
{
"success": false,
"error": {
"code": "INVALID_PRICING_MODEL",
"message": "CPM pricing not available for this audience",
"message": "CPM pricing not available for this signal",
"details": {
"segment_id": "seg_12345",
"requested_model": "cpm",
Expand All @@ -300,7 +300,7 @@ Requested pricing model is not available for this audience.
}
```

**Resolution**: Use available pricing model or choose different audience.
**Resolution**: Use available pricing model or choose different signal.

## Rate Limiting Errors

Expand Down Expand Up @@ -400,7 +400,7 @@ Data quality problem detected.
"success": false,
"error": {
"code": "DATA_QUALITY_ISSUE",
"message": "Audience size data is stale",
"message": "Signal size data is stale",
"details": {
"segment_id": "seg_12345",
"last_updated": "2024-12-01T00:00:00Z",
Expand All @@ -410,7 +410,7 @@ Data quality problem detected.
}
```

**Resolution**: Contact provider for updated audience data.
**Resolution**: Contact provider for updated signal data.

### USAGE_REPORT_REJECTED
Usage report failed validation.
Expand Down Expand Up @@ -487,7 +487,7 @@ Convert technical errors to user-friendly messages:

```typescript
const USER_MESSAGES = {
'SEGMENT_NOT_FOUND': 'This audience is no longer available. Please search for audiences again.',
'SEGMENT_NOT_FOUND': 'This signal is no longer available. Please search for signals again.',
'RATE_LIMIT_EXCEEDED': 'Too many requests. Please wait a moment and try again.',
'INSUFFICIENT_PERMISSIONS': 'Your account does not have permission for this action. Contact your administrator.',
// ... more mappings
Expand Down
Loading
Loading