Agentic Ads
Ad network for AI agents — monetize MCP servers with contextual ads. 70% revenue share.
Open source Repository Open in the app JSON README (API)
About
Ad network for AI agents — monetize MCP servers with contextual ads. 70% revenue share.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- nicofains1
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.2
- Stars
- 2
- Forks
- 1
- Last push
- 2026-04-16T16:39:45Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:54
- Updated
- 2026-08-29 04:00:54
- Origin id
io.github.nicofains1/agentic-ads
README
# Agentic Ads
> **Google AdSense for AI agents.** Add 3 lines of code to your MCP server. Earn 70% of every ad click.
[](https://www.npmjs.com/package/agentic-ads)
[](https://github.com/nicofains1/agentic-ads)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://nodejs.org)
**[Live Demo](https://agentic-ads-production.up.railway.app/health)** · **[Quick Start](#quick-start)** · **[MCP Tools](#mcp-tools-8-total)** · **[Self-Host](#option-3-self-host-production)**
---
## 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](https://agentic-ads-production.up.railway.app/dev/register)**
Or use the API directly:
```bash
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:**
```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:**
```typescript
// 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.
```typescript
// 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
```
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
│ 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:
| 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](https://agentic-ads-production.up.railway.app/dev/register)** and fill in your details. Your API key is displayed immediately.
**Option B — API:**
```bash
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:
```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.):
```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)
```bash
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](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`:
```json
{
"mcpServers": {
"agentic-ads": {
"command": "npx",
"args": ["agentic-ads", "--stdio"]
}
}
}
```
### Cursor / Windsurf
```json
{
"mcpServers": {
"agentic-ads": {
"url": "https://agentic-ads-production.up.railway.app/mcp",
"transport": "http"
}
}
}
```
### Custom TypeScript Agent
```typescript
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`:
```typescript
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`](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
```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:**
```
✅ 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:
```bash
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](scripts/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](https://github.com/nicofains1/agentic-ads/issues/47)).
**Q: Is this open source?**
A: Yes, MIT license. Fork it, self-host it, contribute to it.
---
## Roadmap
- [x] **MVP** — 8 MCP tools, keyword matching, billing, auth, 270 tests
- [x] **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](https://github.com/nicofains1/agentic-ads/issues/40))
- [ ] **Fraud Detection** — Anomaly heuristics ([#47](https://github.com/nicofains1/agentic-ads/issues/47))
- [ ] **Semantic Matching** — Embeddings-based relevance (Phase 2)
- [ ] **A/B Testing** — Ad creative variants ([#41](https://github.com/nicofains1/agentic-ads/issues/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](CLAUDE.md) for detailed guidelines.
---
## Documentation
- **[CLAUDE.md](CLAUDE.md)** — Development guidelines
- **[bulloak.md](bulloak.md)** — Behavioral specification (source of truth for tests)
- **[docs/PRD.md](docs/PRD.md)** — Full Product Requirements Document
- **[scripts/smoke-test.ts](scripts/smoke-test.ts)** — Reference implementation
---
## Support
- **GitHub Issues:** [https://github.com/nicofains1/agentic-ads/issues](https://github.com/nicofains1/agentic-ads/issues)
- **Discussions:** (coming soon)
- **Discord:** (coming soon — join MCP Developers community)
---
## License
MIT — see [LICENSE](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)](https://modelcontextprotocol.io) — the open standard for connecting AI agents to tools.
**Live demo:** [https://agentic-ads-production.up.railway.app](https://agentic-ads-production.up.railway.app)
**Get started:** Add the MCP server to your config, earn your first dollar this week.