Agentic Ads

Agentic Ads

AI エージェント向け 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 — エージェントで 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 エコシステムに欠けていた収益化レイヤーです。ウェブサイト向けではなく、AI エージェント向けの Google AdSense のようなものです。

課題

• 16,000 以上の MCP サーバーが存在します。そのほとんどは収益化されていません。
• 開発者は便利なツールの構築に何週間も費やしても、収益は 0 ドルです。
• ユーザーはエージェントに製品のおすすめを尋ねます → エージェントはウェブをスクレイピングします → ブランドはユーザーにリーチできません。

解決策

MCP ツールを通じて配信される、プライバシーに配慮したコンテキスト広告です。開発者は**収益の 70%**を獲得できます（業界最高水準）。広告主は AI エージェントのユーザーにリーチできます。すべての人にメリットがあります。

---

収益計算ツール

例： 広告が適切な場面で、MCP サーバーが月間 10,000 件のクエリを受け取る場合。

シナリオ	月間インプレッション	CTR	月間クリック数	CPC	あなたの収益
控えめ	10,000	2%	200	$0.50	$70/月
現実的	10,000	5%	500	$0.50	$175/月
好調	10,000	8%	800	$0.75	$420/月

月間 100,000 件のクエリで CTR が 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. ユーザーがエージェントに尋ねます：「マラソンに最適なランニングシューズ」
2. エージェントが search_ads を呼び出し、入札額 × 関連性に基づいて順位付けされた関連広告を取得します
3. エージェントが広告を自然に表示します：「Ultraboost 24 — $126（30% オフ）、Adidas.com にて（スポンサー広告）」
4. ユーザーがクリック → click イベントを報告 → $0.35 を獲得（CPC $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 キーを取得できます
• MCP サーバーを 1 つ設定に追加するだけで、5 分後には収益を獲得できます

3. プライバシーに配慮

• ユーザー追跡やプロファイリングはありません
• Cookie やブラウザーフィンガープリンティングはありません
• コンテキストに基づくキーワード照合のみです（初期の Google AdWords のように）
• ユーザーのプライバシーは守られます

4. 表示する広告は自分で管理できます

• 広告を表示するかどうかをエージェントが決定します
• ユーザーのコンテキスト全体はローカルに保持されます（広告サーバーに送信されることはありません）
• 関連性のしきい値は自分で設定できます
• ユーザーはオプトアウトできます（「広告は表示しないでください」）

5. 透明性の高い分析

• リアルタイムで収益を追跡できます
• いつ、なぜ、いくら獲得したかを正確に確認できます
• ブラックボックスのアルゴリズムや隠れた手数料はありません

---

MCP ツール（合計 8 個）

開発者向け（利用側）— 3 個のツール

ツール	認証	説明
search_ads	公開	クエリ／キーワード／カテゴリ／地域で広告を検索します。関連性スコア付きのランキング結果を返します。
report_event	開発者キー	インプレッション／クリック／コンバージョンのイベントを報告します。収益計算を実行します。
get_ad_guidelines	公開	広告をユーザーに自然に提示するための書式ガイドラインを取得します。

広告主向け（掲載側）— 5 個のツール

ツール	認証	説明
create_campaign	広告主キー	予算、目的、課金モデル（CPC／CPM／CPA）を設定してキャンペーンを作成します。
create_ad	広告主キー	クリエイティブテキスト、キーワード、ターゲティング、リンク URL を指定して広告を作成します。
get_campaign_analytics	広告主キー	パフォーマンス指標（インプレッション、クリック、コンバージョン、消化金額、ROI）を取得します。
update_campaign	広告主キー	キャンペーンを更新します（一時停止／再開、予算の調整、ターゲティングの変更）。
list_campaigns	広告主キー	すべてのキャンペーンを概要統計付きで一覧表示します。ステータスで絞り込むこともできます。

---

料金モデル

支払い方法（広告主）または収益の獲得方法（開発者）を選択できます。

モデル	広告主の支払い額	開発者の収益（70%）	課金のタイミング
CPC（クリック）	クリック 1 回あたり $0.50	$0.35	ユーザーが広告リンクをクリックしたとき
CPM（インプレッション）	1000 回の表示あたり $5.00	$3.50	広告がユーザーに表示されたとき
CPA（コンバージョン）	コンバージョン 1 回あたり $10.00	$7.00	ユーザーがアクション（購入、登録など）を完了したとき

予算管理： 合計予算と 1 日あたりの上限を設定できます。予算を使い切ると自動的に一時停止します。

---

API キーの取得

report_event または広告主向けツールを呼び出すには、API キーが必要です。

方法 A — Web フォーム（最も簡単）：

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

DB の永続化： DATABASE_PATH に永続ボリューム上のパスを設定してください。空の DB で初回実行すると、デモ用キャンペーンが自動的に登録されます。デプロイの詳細については、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 エージェント

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（Server-Sent Events）形式を使用します。レスポンスから 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 リクエスト／分）
• 認証： API キーの SHA-256 ハッシュ化、ロールベースのアクセス制御
• テスト： 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 に達したら、developer_id と希望する支払い方法（PayPal または Polygon 上の USDC）を [email protected] にメールしてください。残高を確認後、5 営業日以内に支払います。ネットワークの拡大に備え、自動 Stripe 支払いをロードマップに加えています。

---

FAQ

開発者向け

Q: API キーを取得するにはどうすればよいですか？ A: 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": "..." }

返された api_key を、MCP リクエストの Authorization: Bearer aa_dev_... として使用してください。

Q: 広告を必ず表示する必要がありますか？ A: いいえ。表示する広告は自分で選べます。ユーザーに本当に価値をもたらす場合にのみ、広告を表示してください。エージェントの自律性は機能の一つです。

Q: ユーザーが広告を嫌がったらどうすればよいですか？ A: get_ad_guidelines のガイドラインに従ってください。レスポンスあたりの広告は最大 1～2 件とし、必ず「スポンサー広告」と明示して、オプトアウト（「広告なしでお願いします」）を尊重してください。

Q: 本番環境で使用できる状態ですか？ A: はい。270 件のテストが成功しており、https://agentic-ads-production.up.railway.app で稼働中です。ライセンスは MIT です。

Q: どの MCP クライアントに対応していますか？ A: stdio または Streamable HTTP に対応する MCP クライアントならどれでも使用できます。Claude Desktop、Cursor、Windsurf、カスタムエージェントでテスト済みです。

広告主向け

Q: 広告を作成するにはどうすればよいですか？ A: 広告主用 API キーを使って、create_campaign および create_ad MCP ツールを使用してください。例については smoke-test.ts を参照してください。

Q: 予算はどのように保護されますか？ A: 予算はアトミックに追跡されます（SQLite トランザクション）。予算が尽きると、キャンペーンは自動的に一時停止します。予算超過はありません。

Q: コンバージョンを追跡できますか？ A: はい。CPA の料金モデルと、event_type: 'conversion' を指定した report_event を使用してください。アトリビューション用に、リンク URL に UTM パラメーターを追加してください。

Q: どのようなターゲティングオプションがありますか？ A: MVP では、キーワード（完全一致および部分一致）、カテゴリ、地域（国単位）、言語を利用できます。セマンティックマッチングはフェーズ 2 で導入予定です。

一般

Q: ユーザーを追跡していますか？ A: いいえ。エージェントから受け取るのは匿名化されたキーワードクエリのみです。ユーザー ID、Cookie、プロファイリングは使用しません。プライバシーを最優先しています。

Q: 不正をどのように防止していますか？ A: MVP では、API キー認証、レート制限、信頼ベースの報告を使用します。フェーズ 2 では、異常検知のヒューリスティクスを追加します（issue #47 を参照）。

Q: オープンソースですか？ A: はい。ライセンスは MIT です。フォークやセルフホスト、コントリビュートが可能です。

---

ロードマップ

• 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 エージェントがウェブを席巻しています。ユーザーは Google で検索する代わりにエージェントに尋ねます。ウェブサイトの代わりにエージェントが回答します。

これまでのインターネット： ユーザーがウェブサイトを閲覧 → 広告を目にする → 広告主がユーザーにリーチする。

これからのインターネット： ユーザーがエージェントに尋ねる → エージェントがウェブサイトをスクレイピングする → 広告主がユーザーにリーチできない。

agentic-ads がこの問題を解決します。 エージェント経済圏の広告レイヤーです。

そして、MCP 開発者であるあなたは、仲介役を担うことで収益の 70% を獲得できます。

この機会： MCP サーバーは 16,000 件以上ある一方、収益化されているものはほとんどありません。先駆けとなるチャンスです。

---

Model Context Protocol (MCP) を使用して構築 — AI エージェントとツールをつなぐオープン標準です。

ライブデモ： https://agentic-ads-production.up.railway.app

始め方： MCP サーバーを設定に追加して、今週最初の収益を獲得しましょう。