Agentic Ads

Agentic Ads

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

[npm version] [Tests] [License: MIT] [MCP] [Node]

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": "[email protected]", "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 relevantconst ads = await mcp.callTool({  name: 'search_ads',  arguments: { query: 'best running shoes for marathon', max_results: 1 }});
// Report events to get paidawait 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.

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/servicesconst 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 impressionawait 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 toolsmcp.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 analyticsmcp.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:

1. User asks your agent: "best running shoes for marathon"
2. Your agent calls search_ads → gets relevant ads ranked by bid × relevance
3. Agent shows ad naturally: "Ultraboost 24 — $126 (30% off) at Adidas.com (Sponsored)"
4. 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:

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

For Advertisers (Publisher Side) — 5 Tools

Pricing Models

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

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": "[email protected]", "project_description": "A coding assistant"}'

Response:

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

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.gitcd agentic-adsnpm install && npm run build
# Start HTTP serverPORT=19877 npm run start:http
# Or stdionpm run start:stdio

Flags:

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

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 adsconst 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 IDconst 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 requestconst 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 repogit clone https://github.com/nicofains1/agentic-ads.gitcd agentic-ads
# Install + buildnpm 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 outputtsx 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 [email protected] 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": "[email protected]"}'# 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:

1. Check if an issue exists for your idea
2. If not: gh issue create --title "Your idea"
3. Get approval before starting work
4. Branch: feature/#N-description
5. Commit: feat(#N): description
6. 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.