Built for Agents

Overview

The Scope3 Agentic API v2 is built from the ground up for AI agents, providing both programmatic REST access and natural language interfaces through the Model Context Protocol (MCP). Whether you’re building agents or using them, Scope3 makes advertising operations conversational and intelligent.

REST API

Traditional HTTP REST API for programmatic integrations with standard HTTP methods.

MCP Protocol

Connect AI agents (Claude, ChatGPT, etc.) to manage campaigns through natural conversation.

Connection Methods

REST API

Standard HTTP REST API for traditional integrations:

Environment	Buyer Base URL	Partner Base URL
Production	`https://api.agentic.scope3.com/api/v2/buyer`	`https://api.agentic.scope3.com/api/v2/partner`
Staging	`https://api.agentic.staging.scope3.com/api/v2/buyer`	`https://api.agentic.staging.scope3.com/api/v2/partner`
Local	`http://localhost:4001/api/v2/buyer`	`http://localhost:4001/api/v2/partner`

MCP (Model Context Protocol)

For AI agent integrations using JSON-RPC 2.0:

Environment	Buyer MCP Endpoint	Partner MCP Endpoint
Production	`https://api.agentic.scope3.com/mcp/v2/buyer`	`https://api.agentic.scope3.com/mcp/v2/partner`
Staging	`https://api.agentic.staging.scope3.com/mcp/v2/buyer`	`https://api.agentic.staging.scope3.com/mcp/v2/partner`
Local	`http://localhost:4001/mcp/v2/buyer`	`http://localhost:4001/mcp/v2/partner`

Available MCP Tools

The v2 Buyer MCP endpoint exposes 3 tools:

Tool	Purpose
`health`	Check API health and verify connectivity
`ask_about_capability`	Query the skill documentation to understand available endpoints
`api_call`	Make authenticated REST API calls to any v2 endpoint

Workflow: AI agents first use ask_about_capability to learn about available endpoints, then use api_call to execute requests.

Testing Locally

Local Development Setup RequiredBefore testing with AI agents locally, ensure your local API server is running:

cd apps/api
pnpm dev

This starts the server at http://localhost:4001

Testing with Claude Desktop

Production
Local Development

For Claude Desktop with production API:Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "scope3-buyer": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.agentic.scope3.com/mcp/v2/buyer"],
      "env": {
        "SCOPE3_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop after saving.

For Claude Desktop with local API:Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "scope3-buyer-local": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:4001/mcp/v2/buyer"],
      "env": {
        "SCOPE3_API_KEY": "your-local-api-key"
      }
    }
  }
}

Restart Claude Desktop after saving.

Testing with Claude Code (CLI)

Production
Local Development

# Add the production MCP server
claude mcp add --transport http scope3-buyer https://api.agentic.scope3.com/mcp/v2/buyer

# Set your API key
export SCOPE3_API_KEY="your-api-key-here"

# Start Claude Code
claude

Then ask: “Use ask_about_capability to learn how to list advertisers, then use api_call to list them”

# Add the local MCP server
claude mcp add --transport http scope3-buyer-local http://localhost:4001/mcp/v2/buyer

# Set your local API key
export SCOPE3_API_KEY="your-local-api-key"

# Start Claude Code
claude

Then ask: “Use ask_about_capability to learn how to list advertisers, then use api_call to list them”

Testing with ChatGPT

Important: ChatGPT MCP connectors can only send OAuth Bearer tokens. Custom headers like x-scope3-api-key are not supported. You must use OAuth authentication.

Production (MCP Connector)
Production (Custom GPT)
Local Development (via ngrok)

Connect ChatGPT to Scope3 via MCP:

Go to ChatGPT → Settings → MCP Connectors
Click Add Connector
Enter MCP Server URL: https://api.agentic.scope3.com/mcp/v2/buyer
Select OAuth as the authentication method
Complete the Scope3 login flow when prompted
Once connected, you’ll have access to 3 tools:
- health - Check API status
- ask_about_capability - Learn about available endpoints
- api_call - Make authenticated API calls
Test with: “Use ask_about_capability to learn how to list advertisers”

Create a Custom GPT with OAuth:

Go to ChatGPT → My GPTs → Create a GPT
Go to Configure → Actions → Create new action
Import the OpenAPI spec:
- Click Import from URL
- Enter: https://api.agentic.scope3.com/api/v2/buyer/openapi.json
Set up OAuth authentication:
- Authentication type: OAuth
- Client ID: (contact Scope3 to register your GPT)
- Authorization URL: https://api.agentic.scope3.com/authorize
- Token URL: https://api.agentic.scope3.com/auth/token
- Scope: openid profile email
Save and test with: “List all my advertisers”

Local development with ChatGPT requires ngrok for HTTPS tunneling and OAuth callback support.

Step 1: Expose your local server

# Install ngrok if you haven't
brew install ngrok  # macOS
# or download from https://ngrok.com/download

# Start your local API server
cd apps/api && pnpm dev

# In another terminal, create a tunnel
ngrok http 4001

ngrok will give you a URL like https://abc123.ngrok.ioStep 2: Configure OAuth redirectAdd your ngrok URL to the allowed OAuth redirect URIs in your local environment.Step 3: Add MCP Connector

Go to ChatGPT → Settings → MCP Connectors
Click Add Connector
Enter your ngrok MCP URL: https://abc123.ngrok.io/mcp/v2
Select OAuth and complete the login flow
Test with: “List all my advertisers”

ngrok URLs change each time you restart. You’ll need to update your MCP connector URL each time. For persistent local testing, consider ngrok’s paid plans for stable URLs.

Testing with Cursor

Production
Local Development

Configure Cursor with production API:

Open Cursor Settings → MCP tab
Add a new MCP server:
- Name: scope3
- URL: https://api.agentic.scope3.com/mcp/v2
- Headers: Authorization: Bearer your-api-key
Restart Cursor
In chat, ask: “Use Scope3 tools to list advertisers”

Configure Cursor with local API:

Open Cursor Settings → MCP tab
Add a new MCP server:
- Name: scope3-local
- URL: http://localhost:4001/mcp/v2
- Headers: Authorization: Bearer your-local-api-key
Restart Cursor
In chat, ask: “Use Scope3 tools to list advertisers”

Testing with curl (REST API)

Production
Local Development

# List advertisers
curl -X GET "https://api.agentic.scope3.com/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json"

# Create an advertiser
curl -X POST "https://api.agentic.scope3.com/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Advertiser", "description": "Created via API"}'

# List advertisers
curl -X GET "http://localhost:4001/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer your-local-api-key" \
  -H "Content-Type: application/json"

# Create an advertiser
curl -X POST "http://localhost:4001/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer your-local-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Advertiser", "description": "Created via API"}'

Testing MCP with curl

Production
Local Development

# Generate a session ID
SESSION_ID=$(uuidgen)

# Initialize MCP session
curl -X POST "https://api.agentic.scope3.com/mcp/v2/buyer" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "curl-test", "version": "1.0"}
    }
  }'

# Call health tool
curl -X POST "https://api.agentic.scope3.com/mcp/v2/buyer" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "health",
      "arguments": {}
    }
  }'

# Call api_call tool to list advertisers
curl -X POST "https://api.agentic.scope3.com/mcp/v2/buyer" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "api_call",
      "arguments": {
        "method": "GET",
        "endpoint": "/api/v2/buyer/advertisers"
      }
    }
  }'

# Generate a session ID
SESSION_ID=$(uuidgen)

# Initialize MCP session
curl -X POST "http://localhost:4001/mcp/v2/buyer" \
  -H "Authorization: Bearer your-local-api-key" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "curl-test", "version": "1.0"}
    }
  }'

# Call health tool
curl -X POST "http://localhost:4001/mcp/v2/buyer" \
  -H "Authorization: Bearer your-local-api-key" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "health",
      "arguments": {}
    }
  }'

# Call api_call tool to list advertisers
curl -X POST "http://localhost:4001/mcp/v2/buyer" \
  -H "Authorization: Bearer your-local-api-key" \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "api_call",
      "arguments": {
        "method": "GET",
        "endpoint": "/api/v2/buyer/advertisers"
      }
    }
  }'

What Your Agents Can Do

Once connected, AI agents use the 3 MCP tools to interact with the full REST API:

The Three Tools

Tool	Purpose	Example
`health`	Verify connectivity	Check if the API is responding
`ask_about_capability`	Learn about endpoints	”How do I create a campaign?”
`api_call`	Execute API requests	POST /api/v2/buyer/campaigns

Example Workflows

Advertiser Management:

Agent asks ask_about_capability “How do I list advertisers?”
Agent uses api_call with GET /api/v2/buyer/advertisers

Campaign Creation:

Agent asks ask_about_capability “How do I create a performance campaign?”
Agent learns about required fields (advertiserId, type, performanceConfig, etc.)
Agent uses api_call with POST /api/v2/buyer/campaigns including the proper body

Example Prompts:

“First use ask_about_capability to learn about creating advertisers, then create one called Acme Corp”
“Check what campaigns exist for advertiser 24”
“Create a $100K performance campaign optimized for SALES”
“Launch the campaign we just created”

Building Custom Agents

Node.js Integration

// REST API example
const response = await fetch('https://api.agentic.scope3.com/api/v2/buyer/advertisers', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.SCOPE3_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const { data } = await response.json();
console.log('Advertisers:', data);

Python Integration

import requests
import os

# REST API example
response = requests.get(
    'https://api.agentic.scope3.com/api/v2/buyer/advertisers',
    headers={
        'Authorization': f'Bearer {os.environ["SCOPE3_API_KEY"]}',
        'Content-Type': 'application/json'
    }
)

advertisers = response.json()['data']
print('Advertisers:', advertisers)

MCP Client Example

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { HttpClientTransport } from '@anthropic-ai/mcp-client-http';

const transport = new HttpClientTransport({
  url: 'https://api.agentic.scope3.com/mcp/v2/buyer',
  headers: {
    'Authorization': `Bearer ${process.env.SCOPE3_API_KEY}`
  }
});

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

// List available tools (health, ask_about_capability, api_call)
const tools = await client.listTools();
console.log('Available tools:', tools.tools.map(t => t.name));

// Check API health
const health = await client.callTool('health', {});
console.log('Health:', health);

// Learn about an endpoint
const docs = await client.callTool('ask_about_capability', {
  query: 'How do I create an advertiser?'
});
console.log('Documentation:', docs);

// Make an API call
const result = await client.callTool('api_call', {
  method: 'GET',
  endpoint: '/api/v2/buyer/advertisers'
});
console.log('Advertisers:', result);

Troubleshooting

Common Issues

Connection refused on localhost

Make sure your local API server is running:

cd apps/api && pnpm dev

Verify it’s listening on port 4001.

401 Unauthorized

Check that:

Your API key is valid
The Authorization header is formatted as Bearer your-api-key
For MCP, the mcp-session-id header is included

Claude Desktop not connecting

Verify your claude_desktop_config.json is valid JSON
Restart Claude Desktop completely (quit and reopen)
Check Claude Desktop logs for errors

ChatGPT custom GPT not working locally

ChatGPT requires HTTPS. Use ngrok or a similar tunnel:

ngrok http 4001

Then use the ngrok HTTPS URL in your custom GPT.

MCP session expired

MCP sessions have a timeout. Initialize a new session:

SESSION_ID=$(uuidgen)
# Then re-initialize with the new session ID

Next Steps

Quick Start

Get started with the v2 API in 5 minutes.

API Reference

Explore all available endpoints and tools.

Authentication

Learn about API keys and authentication.

Overview

Features

Release Notes

Overview

REST API

MCP Protocol

Connection Methods

REST API

MCP (Model Context Protocol)

Available MCP Tools

Testing Locally

Testing with Claude Desktop

Testing with Claude Code (CLI)

Testing with ChatGPT

Testing with Cursor

Testing with curl (REST API)

Testing MCP with curl

What Your Agents Can Do

The Three Tools

Example Workflows

Building Custom Agents

Node.js Integration

Python Integration

MCP Client Example

Troubleshooting

Common Issues

Next Steps

Quick Start

API Reference

Authentication

Overview

Features

Release Notes

​Overview

REST API

MCP Protocol

​Connection Methods

​REST API

​MCP (Model Context Protocol)

​Available MCP Tools

​Testing Locally

​Testing with Claude Desktop

​Testing with Claude Code (CLI)

​Testing with ChatGPT

​Testing with Cursor

​Testing with curl (REST API)

​Testing MCP with curl

​What Your Agents Can Do

​The Three Tools

​Example Workflows

​Building Custom Agents

​Node.js Integration

​Python Integration

​MCP Client Example

​Troubleshooting

​Common Issues

​Next Steps

Quick Start

API Reference

Authentication

Overview

Connection Methods

REST API

MCP (Model Context Protocol)

Available MCP Tools

Testing Locally

Testing with Claude Desktop

Testing with Claude Code (CLI)

Testing with ChatGPT

Testing with Cursor

Testing with curl (REST API)

Testing MCP with curl

What Your Agents Can Do

The Three Tools

Example Workflows

Building Custom Agents

Node.js Integration

Python Integration

MCP Client Example

Troubleshooting

Common Issues

Next Steps