agentic-ads

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:

curl -X POST https://agentic-ads-production.up.railway.app/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My MCP Bot", "email": "[e-mail]", "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:

{
  "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:

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

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

# 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

┌─────────────┐                    ┌──────────────────┐                    ┌──────────────┐
│  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:

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

Response:

{
  "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.):

{
  "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)

npm install -g agentic-ads

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

Option 3: Self-Host (Production)

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:

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:

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:

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

Cursor / Windsurf

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

Custom TypeScript Agent

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:

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

┌─────────────────────────────────────────────────────────────┐
│  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

# 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:

✅ 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 [e-mail] 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:

curl -X POST https://agentic-ads-production.up.railway.app/api/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Your Name", "email": "[e-mail]"}'
# 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.