Agentic Ads

Google AdSense für KI-Agenten. Füge deinem MCP-Server 3 Zeilen Code hinzu. Verdiene 70 % von jedem Werbeklick.

Live-Demo · Schnellstart · MCP-Tools · Selbst hosten

Schnellstart

Schritt 1 – Registrieren und API-Schlüssel erhalten (30 Sekunden):

Besuche das Webformular: https://agentic-ads-production.up.railway.app/dev/register

Oder nutze die API direkt:

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" }

Schritt 2 – Zu deiner MCP-Client-Konfiguration hinzufügen:

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

Schritt 3 – search_ads in deinem Agenten aufrufen und bei jedem Klick verdienen:

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

Das war's. Du monetarisierst.

Related MCP server: superhighway-mcp

Warum es das gibt

Du hast einen großartigen MCP-Server gebaut. Die Nutzer lieben ihn. Aber du verdienst kein Geld.

agentic-ads ist die fehlende Monetarisierungsschicht für das MCP-Ökosystem. Es ist wie Google AdSense, aber für KI-Agenten statt Websites.

Das Problem

• Über 16.000 MCP-Server existieren. Fast keiner monetarisiert.

• Entwickler investieren Wochen in den Bau nützlicher Tools und verdienen 0 $.

• Nutzer fragen Agenten nach Produktempfehlungen → Agenten scrapen das Web → Marken erreichen sie nicht.

Die Lösung

Datenschutzfreundliche kontextbezogene Werbung, die über MCP-Tools ausgeliefert wird. Entwickler erhalten 70 % Umsatzbeteiligung (branchenführend). Werbetreibende erreichen KI-Agenten-Nutzer. Alle gewinnen.

Umsatzrechner

Beispiel: Dein MCP-Server erhält 10.000 Anfragen/Monat, bei denen Werbung sinnvoll ist.

Bei 100.000 Anfragen/Monat mit 5 % Klickrate: 1.750 $/Monat passives Einkommen.

Das sind 21.000 $/Jahr für das Hinzufügen von 3 Zeilen Code zu deinem MCP-Server.

Detaillierte Integrationsanleitung

Für MCP-Entwickler (Geld verdienen)

Verbinde den Live-Server und beginne, Tools aufzurufen – kein Genehmigungsverfahren, keine Mindestbeträge.

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

Für Werbetreibende (KI-Nutzer erreichen)

# 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 } });

Wie es funktioniert

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

Beispielablauf:

1. Nutzer fragt deinen Agenten: „Beste Laufschuhe für Marathon“

2. Dein Agent ruft search_ads auf → erhält relevante Anzeigen, sortiert nach Gebot × Relevanz

3. Agent zeigt Anzeige natürlich an: „Ultraboost 24 – 126 $ (30 % Rabatt) bei Adidas.com (Gesponsert)“

4. Nutzer klickt → du meldest click-Ereignis → du verdienst 0,35 $ (70 % von 0,50 $ CPC)

Datenschutz: Kein Nutzer-Tracking, keine Profilerstellung, keine Cookies. Nur kontextbezogenes Keyword-Matching.

Warum MCP-Entwickler das lieben

1. Branchenführende Umsatzbeteiligung

70 % für dich, 30 % für die Plattform. Vergleich:

2. Null Reibung bei der Einrichtung

• Keine Verträge, keine Mindestbeträge, keine Genehmigungsverzögerungen

• In Sekunden registrieren via POST /api/register → API-Schlüssel erhalten

• 1 MCP-Server zu deiner Konfiguration hinzufügen → in 5 Minuten mit dem Verdienen beginnen

3. Datenschutzfreundlich

• Kein Nutzer-Tracking oder Profiling

• Keine Cookies, kein Browser-Fingerprinting

• Nur kontextbezogenes Keyword-Matching (wie frühes Google AdWords)

• Die Privatsphäre deiner Nutzer bleibt intakt

4. Du kontrollierst, welche Anzeigen geschaltet werden

• Agent entscheidet, welche Anzeigen (falls überhaupt) gezeigt werden

• Vollständiger Nutzerkontext bleibt lokal (wird nie an den Werbeserver gesendet)

• Relevanzschwelle in deinen Händen

• Nutzer können ablehnen („Keine Werbung bitte“)

5. Transparente Analysen

• Echtzeit-Umsatzverfolgung

• Sieh genau, was du wann und warum verdient hast

• Keine Black-Box-Algorithmen oder versteckte Gebühren

MCP-Tools (Insgesamt 8)

Für Entwickler (Nutzerseite) – 3 Tools

Für Werbetreibende (Anbieterseite) – 5 Tools

Preismodelle

Wähle, wie du zahlen (Werbetreibende) oder verdienen (Entwickler) möchtest:

Budgetkontrollen: Lege Gesamtbudget + Tageslimits fest. Automatische Pause bei Budgeterschöpfung.

Deinen API-Schlüssel erhalten

Um report_event oder Werbetreibenden-Tools aufzurufen, benötigst du einen API-Schlüssel.

Option A – Webformular (am einfachsten):

Besuche https://agentic-ads-production.up.railway.app/dev/register und fülle deine Daten aus. Dein API-Schlüssel wird sofort angezeigt.

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": "me@example.com", "project_description": "A coding assistant"}'

Antwort:

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

Verwende den api_key im Authorization-Header: Authorization: Bearer aa_dev_...

Bereitgestellt auf Railway mit persistentem Speicher: Der Live-Server unter agentic-ads-production.up.railway.app läuft auf Railway mit einem persistenten Volume – Daten bleiben über Deployments und Neustarts hinweg erhalten. Zum Selbsthosten verwende DATABASE_PATH=/data/ads.db, der auf ein eingebundenes Volume zeigt.

Installation

Option 1: Mit Live-Server verbinden (Am einfachsten)

Füge zu deiner MCP-Client-Konfiguration hinzu (Claude Desktop, Cursor, Windsurf usw.):

{
  "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: Lokales stdio (Entwicklung)

npm install -g agentic-ads

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

Option 3: Selbst hosten (Produktion)

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

Umgebungsvariablen:

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-Persistenz: Setze DATABASE_PATH auf einen Pfad in einem persistenten Volume. Beim ersten Start mit einer leeren DB werden Demo-Kampagnen automatisch eingefügt. Vollständige Bereitstellungsanleitung in DEPLOY.md (Railway empfohlen für kostenlosen persistenten Speicher).

Integrationsbeispiele

Claude Desktop

Füge zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

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

Benutzerdefinierter 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-Sitzungsverwaltung

Beim Aufruf des Live-Servers über HTTP musst du MCP-Sitzungen manuell verwalten. Hier ein vollständiges Beispiel mit rohem 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);

Wichtige Punkte:

• Der Header mcp-session-id wird bei initialize zurückgegeben und muss bei allen nachfolgenden Anfragen gesendet werden

• Die Authentifizierung (Authorization: Bearer ...) wird pro Sitzung gesetzt – alle Tool-Aufrufe in dieser Sitzung erben sie

• Der Server verwendet SSE-Format (Server-Sent Events) – parsen der data:-Zeile aus der Antwort

• Siehe examples/demo-mcp-server für ein vollständiges funktionierendes Beispiel

Architektur

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

Hauptmerkmale:

• Datenschutz: Kein Nutzer-Tracking, nur kontextbezogenes Matching

• Relevanz: score = relevance² × bidFactor × quality_score (Relevanz dominiert)

• Atomizität: Ereigniseinfügung + Statistikaktualisierung + Umsatzaufteilung in einer einzigen SQLite-Transaktion

• Ratenbegrenzung: Gleitendes Fenster pro Schlüssel (60–120 Anfragen/Minute je nach Tool)

• Authentifizierung: SHA-256-gehashte API-Schlüssel, rollenbasierte Zugriffskontrolle

• Tests: 270 Tests in 13 Dateien, alle bestanden

Demo: Vollständiger Ablauf

# 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_...

Ausgabe:

✅ 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

Wie Entwickler bezahlt werden

Wenn dein MCP-Server ein Klickereignis für eine CPC-Anzeige meldet, gehen 70 % des Gebots an dich – atomar in unserer Datenbank erfasst. Sobald dein Guthaben 10 $ erreicht, sende eine E-Mail an payouts@agentic-ads.com mit deiner developer_id und deiner bevorzugten Zahlungsmethode (PayPal oder USDC auf Polygon). Wir überprüfen dein Guthaben und senden die Zahlung innerhalb von 5 Werktagen. Automatisierte Stripe-Auszahlungen sind für die Zukunft geplant, sobald das Netzwerk skaliert.

FAQ

Für Entwickler

F: Wie erhalte ich einen API-Schlüssel? A: Registriere dich über den REST-Endpunkt:

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": "..." }

Verwende den zurückgegebenen api_key als Authorization: Bearer aa_dev_... in deinen MCP-Anfragen.

F: MUSS ich Anzeigen schalten? A: Nein. Du entscheidest, welche Anzeigen geschaltet werden. Zeige Anzeigen nur, wenn sie dem Nutzer einen echten Mehrwert bieten. Agentenautonomie ist ein Feature.

F: Was, wenn meine Nutzer Werbung hassen? A: Folge den Richtlinien aus get_ad_guidelines: maximal 1–2 Anzeigen pro Antwort, immer „gesponsert“ angeben, Opt-out respektieren („Keine Werbung bitte“).

F: Ist das produktionsreif? A: Ja. 270 bestandene Tests, live unter https://agentic-ads-production.up.railway.app, MIT-Lizenz.

F: Welche MCP-Clients werden unterstützt? A: Jeder MCP-Client, der stdio oder Streamable HTTP unterstützt. Getestet mit Claude Desktop, Cursor, Windsurf, benutzerdefinierten Agenten.

Für Werbetreibende

F: Wie erstelle ich Anzeigen? A: Verwende die MCP-Tools create_campaign und create_ad mit einem Werbetreibenden-API-Schlüssel. Siehe smoke-test.ts für Beispiele.

F: Wie wird mein Budget geschützt? A: Die Budgetverfolgung ist atomar (SQLite-Transaktion). Wenn das Budget erschöpft ist → Kampagne pausiert automatisch. Keine Überschreitung.

F: Kann ich Conversions verfolgen? A: Ja, verwende das CPA-Preismodell + report_event mit event_type: 'conversion'. Füge UTM-Parameter zu deiner Link-URL für die Attribution hinzu.

F: Welche Targeting-Optionen gibt es? A: MVP bietet Keywords (exakte + partielle Übereinstimmung), Kategorien, Geo (Länderebene) und Sprache. Semantisches Matching kommt in Phase 2.

Allgemein

F: Werden Nutzer getrackt? A: Nein. Wir erhalten nur anonymisierte Keyword-Abfragen von Agenten. Keine Benutzer-IDs, keine Cookies, kein Profiling. Datenschutz first.

F: Wie verhindert ihr Betrug? A: MVP verwendet API-Key-Authentifizierung + Ratenbegrenzung + vertrauensbasiertes Melden. Phase 2 fügt Heuristiken zur Anomalieerkennung hinzu (siehe issue #47).

F: Ist das Open Source? A: Ja, MIT-Lizenz. Forke es, hoste es selbst, trage dazu bei.

Roadmap

• MVP — 8 MCP-Tools, Keyword-Matching, Abrechnung, Authentifizierung, 270 Tests

• Bereitgestellt — Live unter https://agentic-ads-production.up.railway.app

• Marketplace-Einträge — Einreichung bei Anthropic Registry, Smithery, Glama, PulseMCP (Woche 1)

• Dashboard REST API — Web-UI für Werbetreibende/Entwickler (#40)

• Betrugserkennung — Anomalie-Heuristiken (#47)

• Semantisches Matching — Embeddings-basierte Relevanz (Phase 2)

• A/B-Testing — Werbevarianten (#41)

• Stripe-Auszahlungen — Automatisierte Entwicklerzahlungen (Phase 3)

Mitwirken

Wir folgen dem GitHub Issues-Workflow:

1. Prüfe, ob es ein Issue für deine Idee gibt

2. Falls nicht: gh issue create --title "Deine Idee"

3. Hole Genehmigung ein, bevor du mit der Arbeit beginnst

4. Branch: feature/#N-Beschreibung

5. Commit: feat(#N): Beschreibung

6. PR an main

Siehe CLAUDE.md für detaillierte Richtlinien.

Dokumentation

• CLAUDE.md — Entwicklungsrichtlinien

• bulloak.md — Verhaltensspezifikation (Quelle der Wahrheit für Tests)

• docs/PRD.md — Vollständiges Produktanforderungsdokument

• scripts/smoke-test.ts — Referenzimplementierung

Support

• GitHub Issues: https://github.com/nicofains1/agentic-ads/issues

• Diskussionen: (demnächst)

• Discord: (demnächst — tritt der MCP Developers-Community bei)

Lizenz

MIT — siehe LICENSE für Details.

Warum das wichtig ist

KI-Agenten fressen das Web. Nutzer fragen Agenten statt Google zu durchsuchen. Agenten antworten statt Websites.

Das alte Internet: Nutzer browsen Websites → sehen Anzeigen → Werbetreibende erreichen Nutzer.

Das neue Internet: Nutzer fragen Agenten → Agenten scrapen Websites → Werbetreibende können Nutzer nicht erreichen.

agentic-ads behebt das. Es ist die Werbeschicht für die Agenten-Ökonomie.

Und du – der MCP-Entwickler – verdienst 70 % der Einnahmen als Vermittler.

Die Chance: 16.000+ MCP-Server, fast keiner monetarisiert. Du kannst der Erste sein.

Erstellt mit Model Context Protocol (MCP) — dem offenen Standard zur Verbindung von KI-Agenten mit Tools.

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

Los geht's: Füge den MCP-Server zu deiner Konfiguration hinzu und verdiene noch diese Woche deinen ersten Dollar.