Agentic Ads

Agentic Ads

面向 AI Agent 的 Google AdSense。 只需向你的 MCP 服务添加 3 行代码。每次广告点击，你都能获得 70% 的收入。

在线演示 · 快速开始 · MCP 工具 · 自行托管

---

快速开始

步骤 1 — 注册并获取 API 密钥（30 秒）：

访问网页表单：https://agentic-ads-production.up.railway.app/dev/register

也可以直接使用 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 that recommends dev tools"}'
# Returns: { "api_key": "aa_dev_...", "mcp_url": "https://agentic-ads-production.up.railway.app/mcp" }

步骤 2 — 添加到 MCP 客户端配置：

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

步骤 3 — 在你的 Agent 中调用 search_ads，每次点击都能获得收入：

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

就是这样。你现在已经开始变现了。

---

为什么要做这个

你打造了一个出色的 MCP 服务，用户很喜欢。但你却没有收入。

agentic-ads 是 MCP 生态中缺失的变现层。它就像 Google AdSense，只不过服务对象是 AI Agent，而不是网站。

问题

• 现有 16,000 多个 MCP 服务，几乎没有一个实现了变现。
• 开发者花数周时间打造实用工具，收入却为 0 美元。
• 用户向 Agent 询问产品推荐 → Agent 抓取网络内容 → 品牌无法触达他们。

解决方案

通过 MCP 工具投放尊重隐私的上下文广告。开发者获得 70% 的收入分成（行业领先）。广告主触达 AI Agent 用户。皆大欢喜。

---

收入计算器

示例： 你的 MCP 服务每月获得 10,000 次查询，其中适合投放广告的查询占一定比例。

情景	每月展示次数	点击率	每月点击次数	单次点击费用	你的收入
保守	10,000	2%	200	$0.50	$70/月
现实	10,000	5%	500	$0.50	$175/月
表现出色	10,000	8%	800	$0.75	$420/月

每月 100k 次查询，点击率为 5%： 每月被动收入 $1,750。

只需向你的 MCP 服务添加 3 行代码，每年就能获得 $21,000。

---

详细集成指南

面向 MCP 开发者（赚取收入）

连接线上服务并开始调用工具——无需审批，也没有最低要求。

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

面向广告主（触达 AI 用户）

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

---

工作原理

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

示例流程：

1. 用户向你的 Agent 提问：“适合马拉松的最佳跑鞋”
2. 你的 Agent 调用 search_ads → 获取按出价 × 相关性排序的相关广告
3. Agent 自然地展示广告：“Ultraboost 24 — $126（优惠 30%），Adidas.com（赞助广告）”
4. 用户点击 → 你上报 click 事件 → 你获得 $0.35（$0.50 单次点击费用的 70%）

隐私： 不跟踪用户、不做用户画像、不使用 Cookie。仅进行上下文关键词匹配。

---

MCP 开发者为何青睐它

1. 行业领先的收入分成

你获得 70%，平台获得 30%。对比：

平台	开发者分成
agentic-ads	70%
Google AdSense	68%
Amazon Associates	1-10%
联盟营销网络	5-30%

2. 设置毫无阻碍

• 无需签订合同、无最低要求、无需等待审批
• 通过 POST /api/register 几秒钟即可注册 → 获取 API 密钥
• 在配置中添加 1 个 MCP 服务 → 5 分钟内开始赚取收入

3. 尊重隐私

• 不跟踪用户，也不做用户画像
• 不使用 Cookie，不进行浏览器指纹识别
• 仅进行上下文关键词匹配（类似早期的 Google AdWords）
• 保护用户隐私不受影响

4. 您可以控制广告展示内容

• Agent 决定展示哪些广告（如果要展示的话）
• 完整的用户上下文保留在本地（绝不会发送给广告服务）
• 相关性阈值由您掌控
• 用户可以选择退出（“请不要展示广告”）

5. 透明的分析数据

• 实时收入追踪
• 准确查看您赚了多少、何时赚到以及原因
• 没有黑箱算法或隐藏费用

---

MCP 工具（共 8 个）

面向开发者（消费端）— 3 个工具

工具	身份验证	描述
search_ads	公开	按查询词／关键词／类别／地理位置搜索广告。返回按相关性评分排序的结果。
report_event	开发者密钥	报告展示／点击／转化事件。触发收入计算。
get_ad_guidelines	公开	获取如何自然地向用户展示广告的格式指南。

面向广告主（发布端）— 5 个工具

工具	身份验证	描述
create_campaign	广告主密钥	创建广告活动，设置预算、目标和定价模式（CPC/CPM/CPA）。
create_ad	广告主密钥	创建广告，设置创意文本、关键词、定向条件和链接 URL。
get_campaign_analytics	广告主密钥	获取效果指标（展示次数、点击次数、转化次数、支出、投资回报率）。
update_campaign	广告主密钥	更新广告活动（暂停／恢复、调整预算、更改定向条件）。
list_campaigns	广告主密钥	列出所有广告活动及其汇总数据，可选按状态筛选。

---

定价模式

选择您希望采用的付费（广告主）或收益（开发者）方式：

模式	广告主支付	开发者获得（70%）	计费时机
CPC（点击）	每次点击 $0.50	$0.35	用户点击广告链接时
CPM（展示）	每 1000 次浏览 $5.00	$3.50	向用户展示广告时
CPA（转化）	每次转化 $10.00	$7.00	用户完成操作时（购买、注册等）

**预算控制：**设置总预算和每日限额。预算用尽时自动暂停。

---

获取您的 API 密钥

要调用 report_event 或广告主工具，您需要 API 密钥。

选项 A — 网页表单（最简单）：

访问 https://agentic-ads-production.up.railway.app/dev/register 并填写您的详细信息。API 密钥会立即显示。

选项 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"}'

响应：

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

字段	必填	描述
name	是	您的项目或机器人名称
email	是	联系邮箱
project_description	否	MCP 服务的简要说明（最多 500 个字符）

在 Authorization 标头中使用 api_key：Authorization: Bearer aa_dev_...

**部署在 Railway 上并使用持久化存储：**位于 agentic-ads-production.up.railway.app 的线上服务运行于 Railway，并使用持久化卷——数据会在部署和重启后保留。要自行托管，请使用 DATABASE_PATH=/data/ads.db 并指向已挂载的卷。

---

安装

选项 1：连接到线上服务（最简单）

将以下内容添加到您的 MCP 客户端配置中（Claude Desktop、Cursor、Windsurf 等）：

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

**健康检查：**https://agentic-ads-production.up.railway.app/health

选项 2：本地 stdio（开发）

npm install -g agentic-ads

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

选项 3：自行托管（生产环境）

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

标志：

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

标志	默认值	描述
--http	—	启动 HTTP 服务（默认使用 stdio）
--port N	3000	HTTP 端口
--db PATH	agentic-ads.db	SQLite 数据库路径
--api-key KEY	—	预先验证 stdio 会话

环境变量：

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

**数据库持久化：**将 DATABASE_PATH 设置为持久化卷上的路径。首次使用空数据库运行时，会自动填充演示广告活动。完整部署指南请参阅 DEPLOY.md（推荐使用 Railway，可免费获得持久化存储）。

---

集成示例

Claude Desktop

添加到 ~/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"
    }
  }
}

自定义 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 会话管理

通过 HTTP 调用线上服务时，必须手动管理 MCP 会话。以下是使用原始 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);

要点：

• initialize 会返回 mcp-session-id 标头，后续所有请求都必须发送该标头
• 身份验证（Authorization: Bearer ...）按会话设置——该会话中的所有工具调用都会继承它
• 服务使用 SSE（服务器发送事件）格式——解析响应中的 data: 行
• 完整可运行的示例见 examples/demo-mcp-server

---

架构

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

主要功能：

• **隐私：**不跟踪用户，仅进行上下文匹配
• 相关性：score = relevance² × bidFactor × quality_score（相关性占主导）
• **原子性：**在单个 SQLite 事务中完成事件插入、统计更新和收入分成
• **速率限制：**按密钥采用滑动窗口（根据工具不同，每分钟 60–120 个请求）
• **身份验证：**使用 SHA-256 哈希的 API 密钥，以及基于角色的访问控制
• **测试：**13 个文件中的 270 项测试全部通过

---

演示：完整流程

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

输出：

✅ 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

---

开发者如何获得报酬

当你的 MCP 服务报告 CPC 广告的点击事件时，出价金额的 70% 将归你所有，并在我们的数据库中以原子方式记录。余额达到 $10 后，请发送邮件至 [email protected]，并提供你的 developer_id 和首选付款方式（PayPal 或 Polygon 上的 USDC）。我们会核实你的余额，并在 5 个工作日内付款。待网络规模扩大后，我们计划推出自动化 Stripe 付款。

---

常见问题

开发者

问：如何获取 API 密钥？ 答：通过 REST 端点注册：

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

在 MCP 请求中，将返回的 api_key 用作 Authorization: Bearer aa_dev_...。

问：我一定要展示广告吗？ 答：不必。你可以决定展示哪些广告。只有在广告确实能为用户带来价值时才展示。Agent 自主性本身就是一项功能。

问：如果我的用户讨厌广告怎么办？ 答：遵循 get_ad_guidelines 中的指南：每次响应最多展示 1–2 条广告，始终注明“赞助”，并尊重用户的退出请求（“请不要展示广告”）。

问：这已经可以用于生产环境了吗？ 答：可以。270 项测试全部通过，服务已上线：https://agentic-ads-production.up.railway.app，采用 MIT 许可证。

问：支持哪些 MCP 客户端？ 答：支持任何兼容 stdio 或 Streamable HTTP 的 MCP 客户端。已在 Claude Desktop、Cursor、Windsurf 和自定义 Agent 中测试。

广告主

问：如何创建广告？ 答：使用广告主 API 密钥调用 MCP 工具 create_campaign 和 create_ad。示例见 smoke-test.ts。

问：如何保障我的预算？ 答：预算跟踪以原子方式执行（SQLite 事务）。预算耗尽时，广告活动会自动暂停，不会超支。

问：可以跟踪转化吗？ 答：可以，使用 CPA 定价模式，并通过 report_event 上报 event_type: 'conversion'。在链接 URL 中添加 UTM 参数即可进行归因。

问：有哪些定向选项？ 答：MVP 支持关键词（精确匹配和部分匹配）、类别、地理位置（国家级）和语言。语义匹配将在第 2 阶段推出。

常见问题

问：你们会跟踪用户吗？ 答：不会。我们只会收到来自 Agent 的匿名关键词查询。不收集用户 ID，不使用 Cookie，也不进行用户画像分析。隐私优先。

问：如何防止欺诈？ 答：MVP 使用 API 密钥身份验证、速率限制和基于信任的报告机制。第 2 阶段将加入异常检测启发式规则（见 issue #47）。

问：这是开源项目吗？ 答：是，采用 MIT 许可证。你可以 fork、自托管，也可以参与贡献。

---

路线图

• MVP — 8 个 MCP 工具、关键词匹配、计费、身份验证、270 项测试
• 已部署 — 已上线：https://agentic-ads-production.up.railway.app
• 市场平台上架 — 提交至 Anthropic Registry、Smithery、Glama、PulseMCP（第 1 周）
• 仪表板 REST API — 面向广告商和开发者的 Web UI（#40）
• 欺诈检测 — 异常启发式规则（#47）
• 语义匹配 — 基于嵌入的相关性匹配（第 2 阶段）
• A/B 测试 — 广告创意变体（#41）
• Stripe 付款 — 自动向开发者付款（第 3 阶段）

---

贡献

我们遵循 GitHub Issues 工作流：

1. 检查是否已有与你的想法相关的 Issue
2. 如果没有：gh issue create --title "Your idea"
3. 开始工作前先获得批准
4. 创建分支：feature/#N-description
5. 提交：feat(#N): description
6. 向 main 提交 PR

详细指南请参阅 CLAUDE.md。

---

文档

• CLAUDE.md — 开发指南
• bulloak.md — 行为规范（测试的权威依据）
• docs/PRD.md — 完整的产品需求文档
• scripts/smoke-test.ts — 参考实现

---

支持

• GitHub Issues： https://github.com/nicofains1/agentic-ads/issues
• 讨论：（即将推出）
• Discord：（即将推出 — 欢迎加入 MCP Developers 社区）

---

许可证

MIT — 详情请参阅 LICENSE。

---

为什么这很重要

AI Agent 正在改变网络。用户不再用 Google 搜索，而是向 Agent 提问。Agent 代替网站给出答案。

旧互联网： 用户浏览网站 → 看到广告 → 广告商触达用户。

新互联网： 用户向 Agent 提问 → Agent 抓取网站 → 广告商无法触达用户。

agentic-ads 正是为此而生。 它是 Agent 经济的广告层。

而你——MCP 开发者——作为中间方，可获得 70% 的收入。

机遇： 16,000 多个 MCP 服务，几乎没有一个实现了变现。你可以抢占先机。

---

基于 Model Context Protocol (MCP) 构建 — 这是连接 AI Agent 与工具的开放标准。

在线演示： https://agentic-ads-production.up.railway.app

开始使用： 将 MCP 服务添加到你的配置中，本周赚取第一笔收入。