Built for Agents

Overview

The Scope3 Agentic API 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	Storefront Base URL
Production	`https://api.agentic.scope3.com/api/buyer`	`https://api.agentic.scope3.com/api/storefront`
Staging	`https://api.agentic.staging.scope3.com/api/buyer`	`https://api.agentic.staging.scope3.com/api/storefront`
Local	`http://localhost:4001/api/buyer`	`http://localhost:4001/api/storefront`

MCP (Model Context Protocol)

For AI agent integrations using JSON-RPC 2.0:

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

These URLs always resolve to the latest stable API version.

Available MCP Tools

The 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 endpoint

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

Authentication

Scope3 supports two authentication methods for connecting agents:

OAuth (Recommended for Claude and ChatGPT)

When connecting via Claude Connectors or ChatGPT MCP Connectors, authentication is handled automatically through OAuth. Users log in with their Scope3 credentials and the agent receives a secure token — no API keys to manage.

API Keys

For programmatic integrations, Claude Code, Cursor, and custom agents, use an API key:

Visit agentic.scope3.com/user-api-keys
Generate a new API key (starts with scope3_)
Pass it via the Authorization: Bearer <key> header

See the Authentication guide for full details.

Connecting AI Agents

Claude Connector (Claude.ai Team / Enterprise)

This is the recommended way to connect Claude to Scope3. It provides OAuth-based authentication and works across both Claude.ai (browser) and Claude Desktop automatically.

Admin Setup (one-time):

Go to claude.ai → Admin Settings → Integrations → MCP Connectors
Click Add Connector
Enter the MCP endpoint URL:
- Production: https://api.agentic.scope3.com/mcp/buyer
- Staging: https://api.agentic.staging.scope3.com/mcp/buyer
Name it (e.g., “Scope3 Agentic API”)
Save the connector — it is now available to all members in your organization

User Setup:

Go to claude.ai → Settings → Integrations → MCP Connectors
Find the Scope3 connector and click Connect
Log in with your Scope3 credentials when prompted (OAuth)
Start chatting! Ask Claude: “List my advertisers” or “Create a performance campaign”

Once connected via the connector, it works in both Claude.ai (browser) and Claude Desktop. No separate configuration needed.

Claude Desktop (Personal / Manual Setup)

If you don’t have a Claude Team or Enterprise plan, you can connect Claude Desktop directly using an API key:

Production
Local Development

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/buyer"],
      "env": {
        "SCOPE3_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop after saving.

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/buyer"],
      "env": {
        "SCOPE3_API_KEY": "your-local-api-key"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code (CLI)

Production
Local Development

# Add the production MCP server
claude mcp add --transport http scope3-buyer https://api.agentic.scope3.com/mcp/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/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”

ChatGPT

Important: ChatGPT MCP connectors use OAuth authentication only. Custom headers like x-scope3-api-key are not supported. Authentication is handled automatically through the OAuth login flow.

MCP Connector
Custom GPT

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/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/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”

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/buyer
- 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/buyer
- Headers: Authorization: Bearer your-local-api-key
Restart Cursor
In chat, ask: “Use Scope3 tools to list advertisers”

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 curl (REST API)

Production
Local Development

# List advertisers
curl -X GET "https://api.agentic.scope3.com/api/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/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/buyer/advertisers" \
  -H "Authorization: Bearer your-local-api-key" \
  -H "Content-Type: application/json"

# Create an advertiser
curl -X POST "http://localhost:4001/api/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/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/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/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/buyer/advertisers"
      }
    }
  }'

# Generate a session ID
SESSION_ID=$(uuidgen)

# Initialize MCP session
curl -X POST "http://localhost:4001/mcp/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/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/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/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/buyer/campaigns

Example Workflows

Advertiser Management:

Agent asks ask_about_capability “How do I list advertisers?”
Agent uses api_call with GET /api/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/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”

Notifications

The Scope3 API includes a notification system that surfaces events about your resources — campaigns going unhealthy, creatives syncing, agents registering, etc. Unread notifications are automatically included in help and ask_about_capability tool responses. To ensure your AI agent proactively surfaces notifications to users, add the following to your agent’s instructions:

Claude Desktop
Claude Code
API / Custom Agent
ChatGPT Custom GPT

Create a Project in Claude Desktop and add this to the project instructions:

When using Scope3 tools, always start by calling the help tool.
The response includes unread notifications — summarize those
for the user before answering their question.

Add to your CLAUDE.md or project instructions:

When using Scope3 tools, always start by calling the help tool.
The response includes unread notifications — summarize those
for the user before answering their question.

Add to your system prompt:

When using Scope3 tools, always start by calling the help tool.
The response includes unread notifications — summarize those
for the user before answering their question.

Add to your Custom GPT’s instructions:

When using Scope3 tools, always start by calling the help tool.
The response includes unread notifications — summarize those
for the user before answering their question.

Notifications can also be managed directly via the REST API:

Operation	Method	Endpoint
List notifications	GET	`/api/buyer/notifications`
Mark as read	POST	`/api/buyer/notifications/{id}/read`
Mark as acknowledged	POST	`/api/buyer/notifications/{id}/acknowledge`
Mark all as read	POST	`/api/buyer/notifications/read-all`

Building Custom Agents

Node.js Integration

// REST API example
const response = await fetch('https://api.agentic.scope3.com/api/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/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/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/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 Connector not appearing

Verify your admin has added the connector in Admin Settings → Integrations → MCP Connectors
Check that you’re on a Claude Team or Enterprise plan
Go to Settings → Integrations → MCP Connectors and click Connect
If prompted, complete the OAuth login with your Scope3 credentials

Claude Desktop not connecting (manual setup)

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

ChatGPT connector not authenticating

ChatGPT only supports OAuth authentication for MCP connectors. Make sure:

You selected OAuth when adding the connector
You completed the Scope3 login flow
Your Scope3 account has access to the API

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 API in 5 minutes.

API Reference

Explore all available endpoints and tools.

Authentication

Learn about API keys and OAuth authentication.

Overview

Features

Integrations

Release Notes

Overview

REST API

MCP Protocol

Connection Methods

REST API

MCP (Model Context Protocol)

Available MCP Tools

Authentication

OAuth (Recommended for Claude and ChatGPT)

API Keys

Connecting AI Agents

Claude Connector (Claude.ai Team / Enterprise)

Claude Desktop (Personal / Manual Setup)

Claude Code (CLI)

ChatGPT

Cursor

Testing Locally

Testing with curl (REST API)

Testing MCP with curl

What Your Agents Can Do

The Three Tools

Example Workflows

Notifications

Building Custom Agents

Node.js Integration

Python Integration

MCP Client Example

Troubleshooting

Common Issues

Next Steps

Quick Start

API Reference

Authentication

Overview

Features

Integrations

Release Notes

​Overview

REST API

MCP Protocol

​Connection Methods

​REST API

​MCP (Model Context Protocol)

​Available MCP Tools

​Authentication

​OAuth (Recommended for Claude and ChatGPT)

​API Keys

​Connecting AI Agents

​Claude Connector (Claude.ai Team / Enterprise)

​Claude Desktop (Personal / Manual Setup)

​Claude Code (CLI)

​ChatGPT

​Cursor

​Testing Locally

​Testing with curl (REST API)

​Testing MCP with curl

​What Your Agents Can Do

​The Three Tools

​Example Workflows

​Notifications

​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

Authentication

OAuth (Recommended for Claude and ChatGPT)

API Keys

Connecting AI Agents

Claude Connector (Claude.ai Team / Enterprise)

Claude Desktop (Personal / Manual Setup)

Claude Code (CLI)

ChatGPT

Cursor

Testing Locally

Testing with curl (REST API)

Testing MCP with curl

What Your Agents Can Do

The Three Tools

Example Workflows

Notifications

Building Custom Agents

Node.js Integration

Python Integration

MCP Client Example

Troubleshooting

Common Issues

Next Steps