Agentic Ads

Google AdSense for AI agents. Add 3 lines of code to your MCP server. Earn 70% of every ad click.

Live Demo · Quick Start · MCP Tools · Self-Host

Quick Start

Step 1 — Register and get your API key (30 seconds):

Visit the web form: https://agentic-ads-production.up.railway.app/dev/register

Or use the API directly:

Terminal

curl -X POST https://agentic-ads-production.up.railway.app/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My MCP Bot", "email": "me@example.com", "project_description": "A coding assistant that recommends dev tools"}'
# Returns: { "api_key": "aa_dev_...", "mcp_url": "https://agentic-ads-production.up.railway.app/mcp" }

Step 2 — Add to your MCP client config:

config.json

{
  "mcpServers": {
    "agentic-ads": {
      "url": "https://agentic-ads-production.up.railway.app/mcp",
      "transport": "http"
    }
  }
}

Step 3 — Call search_ads in your agent and earn on every click:

server.ts

// In your agent logic — when context is relevant
const ads = await mcp.callTool({
  name: 'search_ads',
  arguments: { query: 'best running shoes for marathon', max_results: 1 }
});

// Report events to get paid
await mcp.callTool({
  name: 'report_event',
  arguments: { ad_id: ads[0].ad_id, event_type: 'impression' }
});
// User clicks → report 'click' → you earn $0.35 on a $0.50 CPC ad

That's it. You're monetizing.

Why This Exists

You built an amazing MCP server. Users love it. But you're not making money.

agentic-ads is the missing monetization layer for the MCP ecosystem. It's like Google AdSense, but for AI agents instead of websites.

The Problem

16,000+ MCP servers exist. Almost none monetize.
Developers spend weeks building useful tools, earn $0.
Users ask agents for product recommendations → agents scrape the web → brands can't reach them.

The Solution

Privacy-respecting contextual ads served through MCP tools. Developers earn 70% revenue share (industry-leading). Advertisers reach AI agent users. Everyone wins.

Revenue Calculator

Example: Your MCP server gets 10,000 queries/month where ads make sense.

Scenario	Impressions/mo	CTR	Clicks/mo	CPC	Your Revenue
Conservative	10,000	2%	200	$0.50	$70/mo
Realistic	10,000	5%	500	$0.50	$175/mo
Strong	10,000	8%	800	$0.75	$420/mo

At 100k queries/month with 5% CTR: $1,750/month passive income.

That's $21,000/year for adding 3 lines of code to your MCP server.

Detailed Integration Guide

For MCP Developers (Earn Money)

Connect the live server and start calling tools — no approval process, no minimums.

server.ts

// 1. When user asks about products/services
const ads = await mcp.callTool({
  name: 'search_ads',
  arguments: {
    query: 'best running shoes for marathon',
    max_results: 2
  }
});

// 2. Show relevant ad in your response (if it adds value)
// 3. Report impression
await mcp.callTool({
  name: 'report_event',
  arguments: { ad_id: 'ad_xyz', event_type: 'impression' }
});

// 4. If user clicks → report 'click' event
// You earn $0.35 on a $0.50 CPC click (70% revenue share)

For Advertisers (Reach AI Users)

bash

# Create campaign + ad via MCP tools
mcp.callTool({
  name: 'create_campaign',
  arguments: {
    name: 'Q1 Running Shoes',
    total_budget: 500,
    pricing_model: 'cpc',
    bid_amount: 0.50
  }
});

mcp.callTool({
  name: 'create_ad',
  arguments: {
    campaign_id: 1,
    creative_text: 'Ultraboost 24 — 30% off! Free shipping.',
    link_url: 'https://adidas.com/ultraboost',
    keywords: ['running shoes', 'sneakers', 'marathon'],
    category: 'footwear'
  }
});

# Monitor analytics
mcp.callTool({ name: 'get_campaign_analytics', arguments: { campaign_id: 1 } });

How It Works

Code

┌─────────────┐                    ┌──────────────────┐                    ┌──────────────┐
│  Advertiser  │────────────────────│  Agentic Ads MCP │────────────────────│  Your MCP     │
│  (Brand/API) │  create_campaign   │     Server       │  search_ads        │  Server       │
│              │  create_ad         │                  │  report_event      │               │
│              │  get_analytics     │  - Matching      │  get_guidelines    │  Shows ads    │
└─────────────┘                    │  - Billing       │                    │  to users     │
                                   │  - Auth & Rate   │                    └──────────────┘
                                   │  - Analytics     │
                                   └──────────────────┘

Example flow:

User asks your agent: "best running shoes for marathon"
Your agent calls search_ads → gets relevant ads ranked by bid × relevance
Agent shows ad naturally: "Ultraboost 24 — $126 (30% off) at Adidas.com (Sponsored)"
User clicks → you report click event → you earn $0.35 (70% of $0.50 CPC)

Privacy: No user tracking, no profiling, no cookies. Only contextual keyword matching.

Why MCP Developers Love This

1. Industry-Leading Revenue Share

70% to you, 30% to platform. Compare:

Platform	Developer Share
agentic-ads	70%
Google AdSense	68%
Amazon Associates	1-10%
Affiliate networks	5-30%

2. Zero Setup Friction

No contracts, no minimums, no approval delays
Register in seconds via POST /api/register → get your API key
Add 1 MCP server to your config → start earning in 5 minutes

3. Privacy-Respecting

No user tracking or profiling
No cookies, no browser fingerprinting
Only contextual keyword matching (like early Google AdWords)
Your users' privacy stays intact

4. You Control What Ads Show

Agent decides which ads (if any) to show
Full user context stays local (never sent to ad server)
Relevance threshold in your hands
Users can opt out ("no ads please")

5. Transparent Analytics

Real-time revenue tracking
See exactly what you earned, when, and why
No black-box algorithms or hidden fees

MCP Tools (8 Total)

For Developers (Consumer Side) — 3 Tools

Tool	Auth	Description
`search_ads`	Public	Search for ads by query/keywords/category/geo. Returns ranked results with relevance scores.
`report_event`	Developer key	Report impression/click/conversion events. Triggers revenue calculation.
`get_ad_guidelines`	Public	Get formatting guidelines for how to present ads naturally to users.

For Advertisers (Publisher Side) — 5 Tools

Tool	Auth	Description
`create_campaign`	Advertiser key	Create campaign with budget, objective, pricing model (CPC/CPM/CPA).
`create_ad`	Advertiser key	Create ad with creative text, keywords, targeting, link URL.
`get_campaign_analytics`	Advertiser key	Get performance metrics (impressions, clicks, conversions, spend, ROI).
`update_campaign`	Advertiser key	Update campaign (pause/resume, adjust budget, change targeting).
`list_campaigns`	Advertiser key	List all campaigns with summary stats, optional status filter.

Pricing Models

Choose how you want to pay (advertisers) or earn (developers):

Model	Advertiser Pays	Developer Earns (70%)	When Charged
CPC (Click)	$0.50 per click	$0.35	User clicks ad link
CPM (Impression)	$5.00 per 1000 views	$3.50	Ad shown to user
CPA (Conversion)	$10.00 per conversion	$7.00	User completes action (purchase, signup, etc.)

Budget controls: Set total budget + daily caps. Auto-pause when budget exhausted.

Getting Your API Key

To call report_event or advertiser tools, you need an API key.

Option A — Web form (easiest):

Visit https://agentic-ads-production.up.railway.app/dev/register and fill in your details. Your API key is displayed immediately.

Option B — API:

Terminal

curl -X POST https://agentic-ads-production.up.railway.app/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My MCP Bot", "email": "me@example.com", "project_description": "A coding assistant"}'

Response:

config.json

{
  "developer_id": "...",
  "api_key": "aa_dev_...",
  "mcp_url": "https://agentic-ads-production.up.railway.app/mcp"
}

Field	Required	Description
`name`	Yes	Your project or bot name
`email`	Yes	Contact email
`project_description`	No	Brief description of your MCP server (max 500 chars)

Use the api_key in the Authorization header: Authorization: Bearer aa_dev_...

Deployed on Railway with persistent storage: The live server at agentic-ads-production.up.railway.app runs on Railway with a persistent volume — data is preserved across deploys and restarts. To self-host, use DATABASE_PATH=/data/ads.db pointing to a mounted volume.

Installation

Option 1: Connect to Live Server (Easiest)

Add to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.):

config.json

{
  "mcpServers": {
    "agentic-ads": {
      "url": "https://agentic-ads-production.up.railway.app/mcp",
      "transport": "http"
    }
  }
}

Health check: https://agentic-ads-production.up.railway.app/health

Option 2: Local stdio (Development)

Terminal

npm install -g agentic-ads

# Add to MCP config
{
  "mcpServers": {
    "agentic-ads": {
      "command": "npx",
      "args": ["agentic-ads", "--stdio"]
    }
  }
}

Option 3: Self-Host (Production)

bash

git clone https://github.com/nicofains1/agentic-ads.git
cd agentic-ads
npm install && npm run build

# Start HTTP server
PORT=19877 npm run start:http

# Or stdio
npm run start:stdio

Flags:

bash

node dist/server.js --http --port 19877 --db ./ads.db

Flag	Default	Description
`--http`	—	Start HTTP server (default is stdio)
`--port N`	`3000`	HTTP port
`--db PATH`	`agentic-ads.db`	SQLite database path
`--api-key KEY`	—	Pre-authenticate stdio sessions

Environment Variables:

bash

PORT=19877                     # HTTP server port (alternative to --port)
DATABASE_PATH=/data/ads.db     # SQLite database path (default: agentic-ads.db)
AGENTIC_ADS_API_KEY=aa_dev_... # Developer API key for stdio mode

DB Persistence: Set DATABASE_PATH to a path on a persistent volume. On first run with an empty DB, demo campaigns are auto-seeded. See DEPLOY.md for full deployment guide (Railway recommended for free persistent storage).

Integration Examples

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

config.json

{
  "mcpServers": {
    "agentic-ads": {
      "command": "npx",
      "args": ["agentic-ads", "--stdio"]
    }
  }
}

Cursor / Windsurf

config.json

{
  "mcpServers": {
    "agentic-ads": {
      "url": "https://agentic-ads-production.up.railway.app/mcp",
      "transport": "http"
    }
  }
}

Custom TypeScript Agent

server.ts

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['agentic-ads', '--stdio']
});

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

// Search for ads
const result = await client.callTool({
  name: 'search_ads',
  arguments: {
    query: 'best laptops for coding',
    keywords: ['laptop', 'programming'],
    category: 'electronics',
    max_results: 3
  }
});

console.log(result.content[0].text);
// Returns: { "ads": [ { "ad_id": "...", "creative_text": "...", "relevance_score": 0.87 } ] }

Streamable HTTP Session Management

When calling the live server over HTTP, you must manage MCP sessions manually. Here's a complete example using raw fetch:

server.ts

const BASE = "https://agentic-ads-production.up.railway.app";
const API_KEY = "aa_dev_..."; // from /api/register

const headers = {
  "Content-Type": "application/json",
  "Accept": "application/json, text/event-stream",
  "Authorization": `Bearer ${API_KEY}`,
};

// 1. Initialize — get a session ID
const initRes = await fetch(`${BASE}/mcp`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    jsonrpc: "2.0", id: 1, method: "initialize",
    params: {
      protocolVersion: "2024-11-05",
      capabilities: {},
      clientInfo: { name: "my-agent", version: "1.0.0" },
    },
  }),
});
const sessionId = initRes.headers.get("mcp-session-id");

// 2. Send initialized notification (required by MCP spec)
await fetch(`${BASE}/mcp`, {
  method: "POST",
  headers: { ...headers, "mcp-session-id": sessionId },
  body: JSON.stringify({
    jsonrpc: "2.0", method: "notifications/initialized", params: {},
  }),
});

// 3. Call tools — pass session ID on every request
const res = await fetch(`${BASE}/mcp`, {
  method: "POST",
  headers: { ...headers, "mcp-session-id": sessionId },
  body: JSON.stringify({
    jsonrpc: "2.0", id: 2, method: "tools/call",
    params: { name: "search_ads", arguments: { query: "running shoes", max_results: 2 } },
  }),
});

// 4. Parse response (SSE format: "event: message\ndata: {...}")
const text = await res.text();
const dataLine = text.split("\n").find((l) => l.startsWith("data:"));
const result = JSON.parse(dataLine.slice(5));
console.log(result.result.content[0].text);

Key points:

The mcp-session-id header is returned on initialize and must be sent on all subsequent requests
Auth (Authorization: Bearer ...) is set per-session — all tool calls in that session inherit it
The server uses SSE (Server-Sent Events) format — parse the data: line from the response
See examples/demo-mcp-server for a full working example

Architecture

Code

┌─────────────────────────────────────────────────────────────┐
│  MCP Server (Node.js 22 + TypeScript)                       │
│  ┌───────────────┐  ┌──────────────┐  ┌─────────────────┐  │
│  │ Tool Registry │  │ Auth & Rate  │  │ Matching Engine │  │
│  │ (8 tools)     │  │ Limiting     │  │ (relevance²     │  │
│  │               │  │ (SHA-256)    │  │ × bid × quality)│  │
│  └───────────────┘  └──────────────┘  └─────────────────┘  │
│  ┌───────────────┐  ┌──────────────┐  ┌─────────────────┐  │
│  │ SQLite (WAL)  │  │ Revenue      │  │ Analytics       │  │
│  │ - Campaigns   │  │ Split Engine │  │ (real-time)     │  │
│  │ - Ads         │  │ (70/30)      │  │                 │  │
│  │ - Events      │  │              │  │                 │  │
│  └───────────────┘  └──────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────────┘
          │                                          │
          │                                          │
  Streamable HTTP (remote)                     stdio (local)

Key Features:

Privacy: No user tracking, contextual matching only
Relevance: score = relevance² × bidFactor × quality_score (relevance dominates)
Atomicity: Event insert + stats update + revenue split in single SQLite transaction
Rate Limiting: Per-key sliding window (60-120 req/min depending on tool)
Auth: SHA-256 hashed API keys, role-based access control
Testing: 270 tests across 13 files, all passing

Demo: Full Flow

bash

# Clone repo
git clone https://github.com/nicofains1/agentic-ads.git
cd agentic-ads

# Install + build
npm install && npm run build

# Seed a local DB with demo data (generates real API keys)
tsx scripts/seed.ts --db test.db
# Note: seed.ts prints the generated dev/adv keys — use them below

# Run smoke test with real keys from seed output
tsx scripts/smoke-test.ts --db test.db --dev-key aa_dev_... --adv-key aa_adv_...

Output:

Code

✅ Created advertiser: Adidas
✅ Created campaign: Q1 Running Shoes ($500 budget, CPC $0.50)
✅ Created ad: "Ultraboost 24 — 30% off!"
✅ Created developer: TestBot
✅ Searched ads for "running shoes" → 1 result (relevance 0.95)
✅ Reported impression → $0.00 charged (CPC model)
✅ Reported click → $0.50 charged, developer earned $0.35
✅ Analytics: 1 impression, 1 click, $0.50 spent, $0.35 developer revenue

How Developers Get Paid

When your MCP server reports a click event on a CPC ad, 70% of the bid goes to you — tracked atomically in our database. Once your balance reaches $10, email payouts@agentic-ads.com with your developer_id and your preferred payment method (PayPal or USDC on Polygon). We verify your balance and send payment within 5 business days. Automated Stripe payouts are on the roadmap for when the network scales.

FAQ

For Developers

Q: How do I get an API key? A: Register via the REST endpoint:

Terminal

curl -X POST https://agentic-ads-production.up.railway.app/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Your Name", "email": "you@example.com"}'
# Returns: { "developer_id": "...", "api_key": "aa_dev_...", "mcp_url": "..." }

Use the returned api_key as Authorization: Bearer aa_dev_... in your MCP requests.

Q: Do I HAVE to show ads? A: No. You control which ads to show. Only show ads if they genuinely add value to the user. Agent autonomy is a feature.

Q: What if my users hate ads? A: Follow the guidelines from get_ad_guidelines: max 1-2 ads per response, always disclose "sponsored", respect opt-out ("no ads please").

Q: Is this production-ready? A: Yes. 270 passing tests, live at https://agentic-ads-production.up.railway.app, MIT license.

Q: What MCP clients are supported? A: Any MCP client supporting stdio or Streamable HTTP. Tested with Claude Desktop, Cursor, Windsurf, custom agents.

For Advertisers

Q: How do I create ads? A: Use the create_campaign and create_ad MCP tools with an advertiser API key. See smoke-test.ts for examples.

Q: How is my budget protected? A: Budget tracking is atomic (SQLite transaction). When budget exhausted → campaign auto-pauses. No overspend.

Q: Can I track conversions? A: Yes, use CPA pricing model + report_event with event_type: 'conversion'. Add UTM params to your link URL for attribution.

Q: What targeting options exist? A: MVP has keywords (exact + partial match), categories, geo (country-level), and language. Semantic matching coming in Phase 2.

General

Q: Do you track users? A: No. We only receive anonymized keyword queries from agents. No user IDs, no cookies, no profiling. Privacy-first.

Q: How do you prevent fraud? A: MVP uses API key auth + rate limiting + trust-based reporting. Phase 2 adds anomaly detection heuristics (see issue #47).

Q: Is this open source? A: Yes, MIT license. Fork it, self-host it, contribute to it.

Roadmap

MVP — 8 MCP tools, keyword matching, billing, auth, 270 tests
Deployed — Live at https://agentic-ads-production.up.railway.app
Marketplace Listings — Submit to Anthropic Registry, Smithery, Glama, PulseMCP (Week 1)
Dashboard REST API — Web UI for advertisers/developers (#40)
Fraud Detection — Anomaly heuristics (#47)
Semantic Matching — Embeddings-based relevance (Phase 2)
A/B Testing — Ad creative variants (#41)
Stripe Payouts — Automated developer payments (Phase 3)

Contributing

We follow the GitHub Issues workflow:

Check if an issue exists for your idea
If not: gh issue create --title "Your idea"
Get approval before starting work
Branch: feature/#N-description
Commit: feat(#N): description
PR to main

See CLAUDE.md for detailed guidelines.

Documentation

CLAUDE.md — Development guidelines
bulloak.md — Behavioral specification (source of truth for tests)
docs/PRD.md — Full Product Requirements Document
scripts/smoke-test.ts — Reference implementation

Support

GitHub Issues: https://github.com/nicofains1/agentic-ads/issues
Discussions: (coming soon)
Discord: (coming soon — join MCP Developers community)

License

MIT — see LICENSE for details.

Why This Matters

AI agents are eating the web. Users ask agents instead of searching Google. Agents answer instead of websites.

The old internet: Users browse websites → see ads → advertisers reach users.

The new internet: Users ask agents → agents scrape websites → advertisers can't reach users.

agentic-ads fixes this. It's the ad layer for the agent economy.

And you — the MCP developer — earn 70% of the revenue for being the intermediary.

The opportunity: 16,000+ MCP servers, almost none monetize. You can be first.

Built with Model Context Protocol (MCP) — the open standard for connecting AI agents to tools.

Live demo: https://agentic-ads-production.up.railway.app

Get started: Add the MCP server to your config, earn your first dollar this week.