AdCP Quickstart Guide

Get started with AdCP in 5 minutes. This guide shows you how to test AdCP, understand authentication, and make your first requests.

Try AdCP Right Now

Interactive Testing Platform

The fastest way to explore AdCP is through our interactive testing platform: 🔗 https://testing.adcontextprotocol.org This platform lets you:

Test all AdCP tasks interactively
See real request/response examples
Validate your understanding of the protocol
Try different scenarios without writing code

Test Agent for Development

For developers building AdCP integrations, we provide a public test agent with free credentials: Agent URL: https://test-agent.adcontextprotocol.org Agent Card: https://test-agent.adcontextprotocol.org/.well-known/agent-card.json Free Test Credentials: For MCP Protocol:

{
  "agent_uri": "https://test-agent.adcontextprotocol.org/mcp",
  "protocol": "mcp",
  "version": "1.0",
  "auth": {
    "type": "bearer",
    "token": "1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ"
  }
}

For A2A Protocol:

{
  "agent_uri": "https://test-agent.adcontextprotocol.org/a2a",
  "protocol": "a2a",
  "version": "1.0",
  "auth": {
    "type": "bearer",
    "token": "L4UCklW_V_40eTdWuQYF6HD5GWeKkgV8U6xxK-jwNO8"
  }
}

What You Can Do:

✅ Test all AdCP tasks with authentication
✅ See complete product catalogs with pricing
✅ Create test media buys (with dry run mode)
✅ Upload and sync test creatives
✅ Practice integration patterns

Important: This is a test agent. Data is ephemeral and may be reset. Use dry run mode to avoid creating actual test campaigns.

Understanding Authentication

AdCP uses a tiered authentication model - some operations work without credentials, while others require authentication.

Operations That DON’T Require Authentication

These capability discovery operations work without credentials:

✅ list_creative_formats - Browse available creative formats
✅ list_authorized_properties - See which properties an agent represents
✅ get_products - Discover inventory (limited results without auth)

Why these are public: Publishers want potential buyers to discover their inventory and understand their capabilities before establishing a relationship. Important: Unauthenticated get_products requests may return:

Limited product catalog
No pricing information
Generic products only
No custom offerings

Operations That REQUIRE Authentication

These operations require valid credentials:

🔒 get_products (full results) - See complete catalog with pricing
🔒 create_media_buy - Create advertising campaigns
🔒 update_media_buy - Modify existing campaigns
🔒 sync_creatives - Upload creative assets
🔒 list_creatives - View your creative library
🔒 get_media_buy_delivery - Monitor campaign performance
🔒 provide_performance_feedback - Submit optimization signals

Why authentication is required: These operations involve financial commitments, access to proprietary data, or modifications to campaigns.

Getting Credentials

To access authenticated operations, you need to establish an account with each sales agent you want to work with.

How to Get Access

1. Contact the Sales Agent Each AdCP sales agent manages their own accounts and credentials. Find their contact information via:

The agent’s website (discovered via adagents.json)
Direct outreach to the publisher
Through aggregation platforms (like Scope3)

2. Credential Types Sales agents typically support one or both:

API Keys: Simple header-based authentication (X-API-Key: <key>)
JWT Tokens: OAuth-based authentication (Authorization: Bearer <token>)

See Authentication Reference for technical details. 3. Dynamic Registration (Optional) Some sales agents support OAuth-based dynamic registration - check their documentation or adagents.json file for details.

Working with Multiple Agents

Important: You need separate credentials for each sales agent.

Your App
├── Sales Agent A (ESPN inventory)
│   └── Requires ESPN credentials
├── Sales Agent B (Weather.com inventory)
│   └── Requires Weather.com credentials
└── Sales Agent C (Multi-publisher network)
    └── Requires network credentials

Aggregation Platforms: Consider using platforms like Scope3 that manage credentials and relationships with multiple sales agents on your behalf.

Your First Request

Let’s make a test request using the public test agent with authentication.

Step 1: Test with Authentication

Use the test agent credentials provided above to make an authenticated request: Using MCP (JSON-RPC 2.0):

curl -X POST https://test-agent.adcontextprotocol.org/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-123",
    "method": "tools/call",
    "params": {
      "name": "get_products",
      "arguments": {
        "promoted_offering": "Nike Air Max 2024 - latest innovation in cushioning technology"
      }
    }
  }'

Expected Response (Server-Sent Events format):

event: message
data: {"status":"success","products":[...],"message":"Found 3 products..."}

Step 2: Interpret the Response

The response includes:

message: Human-readable summary of results
products: Array of available inventory products with pricing information
context_id: Session identifier for follow-up requests

With authentication, you’ll see:

✅ Complete product catalog
✅ Pricing information (CPM, min_spend)
✅ Custom product offerings
✅ Measurement capabilities

Step 3: Try Without Authentication

Compare by making the same request without the Authorization header:

curl -X POST https://test-agent.adcontextprotocol.org/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-123",
    "method": "tools/call",
    "params": {
      "name": "get_products",
      "arguments": {
        "promoted_offering": "Nike Air Max 2024 - latest innovation in cushioning technology"
      }
    }
  }'

You’ll notice fewer products and missing pricing details - this demonstrates the tiered authentication model.

Testing with Dry Run Mode

AdCP supports comprehensive testing without spending real money or affecting production systems.

Enable Dry Run Mode

Add the X-Dry-Run header to any request:

curl -X POST <agent-url> \
  -H "X-Dry-Run: true" \
  -H "Authorization: Bearer <token>" \
  -d '{...}'

What Dry Run Does:

✅ Validates your request structure
✅ Returns realistic simulated responses
✅ Tests error scenarios
❌ Does NOT create real campaigns
❌ Does NOT spend actual money
❌ Does NOT affect production systems

Learn more: Testing & Development Guide

Protocol Choice: MCP vs A2A

AdCP tasks work identically across protocols - choose based on your technical needs:

Use MCP if:

You’re integrating with Claude or MCP-compatible AI assistants
You prefer direct tool-calling patterns
Your client already supports MCP

Use A2A if:

You’re using Google’s agent ecosystem
You prefer message-based interactions with Server-Sent Events
Your client already supports A2A

The tasks are the same - get_products, create_media_buy, etc. work identically in both protocols, just with different request/response wrappers. Learn more: Protocol Comparison

Using the NPM Client

If you’re building in Node.js, use the official AdCP client:

npm install @adcp/client

Example usage with test agent:

import { AdcpClient } from '@adcp/client';

// Use the public test agent
const client = new AdcpClient({
  agentUrl: 'https://test-agent.adcontextprotocol.org/mcp',
  protocol: 'mcp',
  bearerToken: '1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ'  // Test agent token
});

// Test authenticated product discovery
const products = await client.getProducts({
  promoted_offering: 'Nike Air Max 2024 - innovative cushioning technology'
});

console.log(`Found ${products.products.length} products`);
console.log('First product:', products.products[0]);

// Test with dry run mode
const mediaBuy = await client.createMediaBuy({
  product_id: products.products[0].product_id,
  budget: 10000,
  start_date: '2025-11-01',
  end_date: '2025-11-30'
}, {
  dryRun: true  // No actual campaign created
});

console.log('Test media buy created:', mediaBuy.media_buy_id);

Common Issues

”Invalid request parameters” Error

Problem: You’re sending incorrect parameters or using an outdated schema. Solution:

Verify you’re using the latest AdCP version (check schema registry)
Check parameter names match the task reference docs
Use the testing platform to validate your request structure

Missing Pricing Information

Problem: Products return without CPM or pricing details. Solution: You need to authenticate. Unauthenticated requests only return limited public information.

”Authentication required” Error

Problem: Trying to access an authenticated operation without credentials. Solution: Get credentials from the sales agent, then include them in your request headers.

Next Steps

Now that you understand the basics:

Explore the Protocol:
- Try the interactive testing platform
- Read the MCP Guide or A2A Guide
- Review the Task Reference
Get Credentials:
- Identify sales agents you want to work with (check their adagents.json files)
- Contact them to establish accounts
- Test authenticated operations
Build Your Integration:
- Install the @adcp/client NPM package
- Follow the implementation patterns
- Use dry run mode to test safely
Join the Community:
- Slack Community
- GitHub Discussions
- Email: support@adcontextprotocol.org

Key Takeaways

✅ Test without code - Use https://testing.adcontextprotocol.org ✅ Discovery is public - list_creative_formats, list_authorized_properties, and basic get_products work without auth ✅ Full access needs credentials - Contact each sales agent to get accounts ✅ Dry run mode - Test safely without spending money ✅ Protocol agnostic - Same tasks work in MCP and A2A ✅ NPM client available - Use @adcp/client for Node.js projects

Getting Started

Protocols

Signals Protocol

Curation Protocol

Media Buy Protocol

Creative

Reference

Quickstart Guide

AdCP Quickstart Guide

Try AdCP Right Now

Interactive Testing Platform

Test Agent for Development

Understanding Authentication

Operations That DON’T Require Authentication

Operations That REQUIRE Authentication

Getting Credentials

How to Get Access

Working with Multiple Agents

Your First Request

Step 1: Test with Authentication

Step 2: Interpret the Response

Step 3: Try Without Authentication

Testing with Dry Run Mode

Enable Dry Run Mode

Protocol Choice: MCP vs A2A

Use MCP if:

Use A2A if:

Using the NPM Client

Common Issues

”Invalid request parameters” Error

Missing Pricing Information

”Authentication required” Error

Next Steps

Key Takeaways

Getting Started

Protocols

Signals Protocol

Curation Protocol

Media Buy Protocol

Creative

Reference

​AdCP Quickstart Guide

​Try AdCP Right Now

​Interactive Testing Platform

​Test Agent for Development

​Understanding Authentication

​Operations That DON’T Require Authentication

​Operations That REQUIRE Authentication

​Getting Credentials

​How to Get Access

​Working with Multiple Agents

​Your First Request

​Step 1: Test with Authentication

​Step 2: Interpret the Response

​Step 3: Try Without Authentication

​Testing with Dry Run Mode

​Enable Dry Run Mode

​Protocol Choice: MCP vs A2A

​Use MCP if:

​Use A2A if:

​Using the NPM Client

​Common Issues

​”Invalid request parameters” Error

​Missing Pricing Information

​”Authentication required” Error

​Next Steps

​Key Takeaways

AdCP Quickstart Guide

Try AdCP Right Now

Interactive Testing Platform

Test Agent for Development

Understanding Authentication

Operations That DON’T Require Authentication

Operations That REQUIRE Authentication

Getting Credentials

How to Get Access

Working with Multiple Agents

Your First Request

Step 1: Test with Authentication

Step 2: Interpret the Response

Step 3: Try Without Authentication

Testing with Dry Run Mode

Enable Dry Run Mode

Protocol Choice: MCP vs A2A

Use MCP if:

Use A2A if:

Using the NPM Client

Common Issues

”Invalid request parameters” Error

Missing Pricing Information

”Authentication required” Error

Next Steps

Key Takeaways