{
  "markdown": "# AdsMCP\n\n**The ad monetization MCP server for AI applications.**\n\nAdsMCP is Adgentek's hosted Model Context Protocol server that enables AI agents and conversational interfaces to serve contextually relevant ads automatically — based on conversation context, user intent, and placement opportunity.\n\nBuilt on a full ad server stack. Bring live demand from Adgentek, bring your own direct-sold campaigns, or both. No ad tech expertise required.\n\n---\n\n## Before You Start\n\n**You need an Adgentek publisher account, an API key, and at least one active AI Surface before ads will serve.**\n\n[**Create your publisher account →**](https://app.adgentek.ai/publishers/auth)\n\n### Setup checklist\n\n1. **Create your account** at [app.adgentek.ai/publishers/auth](https://app.adgentek.ai/publishers/auth)\n2. **Create an AI Surface** — in the publisher dashboard, go to **Inventory → Surfaces** and add at least one surface (e.g. `conversational`, `search`, `voice`). A surface defines where ads can appear and sets your floor eCPM.\n3. **Generate an API key** — in the publisher dashboard, go to **Settings → API Keys** and create a key (prefixed `adgt_`). This key authenticates all MCP requests.\n\nYour account is considered **Active** once at least one surface is enabled.\n\n---\n\n## Connect\n\n```json\n{\n  \"mcpServers\": {\n    \"adgentek-ads\": {\n      \"url\": \"https://mcp.adgentek.ai/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\nThis is the only configuration needed. All MCP-compatible clients support this URL + Headers pattern — no local packages or environment variables required.\n\n---\n\n## Platform-Specific Configuration\n\nThe connection config is identical across platforms. Only the file location and wrapper key differ.\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\n```json\n// ~/Library/Application Support/Claude/claude_desktop_config.json  (macOS)\n// %APPDATA%\\Claude\\claude_desktop_config.json  (Windows)\n{\n  \"mcpServers\": {\n    \"adgentek-ads\": {\n      \"url\": \"https://mcp.adgentek.ai/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\n```json\n// ~/.claude/settings.json\n{\n  \"mcpServers\": {\n    \"adgentek-ads\": {\n      \"url\": \"https://mcp.adgentek.ai/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\n```json\n// .cursor/mcp.json\n{\n  \"mcpServers\": {\n    \"adgentek-ads\": {\n      \"url\": \"https://mcp.adgentek.ai/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>VS Code (Copilot MCP)</strong></summary>\n\n```json\n// .vscode/mcp.json\n{\n  \"servers\": {\n    \"adgentek-ads\": {\n      \"url\": \"https://mcp.adgentek.ai/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>OpenAI Codex</strong></summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"adgentek-ads\": {\n      \"url\": \"https://mcp.adgentek.ai/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n</details>\n\n---\n\n## Available Tools\n\n### `ads.serve`\n\nServes a contextual ad based on the current conversation. Returns the highest-yield ad available for the given context, or `null` if no ad matched.\n\n**Required parameters:** `conversationId`, `userKey`, `surface`\n\n**Optional parameters:** `messages`, `intent`, `sentiment`, `depth`, `language`, `geo`, `preferHtml`, `extras`\n\n```javascript\nconst result = await callTool('ads.serve', {\n  conversationId: 'conv_abc123',\n  userKey:        'user_456',\n  surface:        'conversational',\n  messages: [\n    { role: \"user\",      content: \"What CRM works best for a small sales team?\" },\n    { role: \"assistant\", content: \"For small teams, a few options stand out...\" },\n    { role: \"user\",      content: \"Which ones integrate with Google Workspace?\" }\n  ],\n  intent:    'research',\n  sentiment: 65,\n  depth:     3,\n  language:  'en',\n  geo:       'US'\n});\n\nif (result.ad) {\n  displayAd(result.ad.render.markdown);\n  // Impressions: embed ad.impression_url as a 1x1 pixel in the browser\n  // Clicks: use ad.click_url as the CTA link href\n}\n```\n\n**Surface types:** `conversational`, `search`, `voice`, `creative`, `web`\n\n**Intent values:** `purchase`, `research`, `support`, `informational`\n\n---\n\n### `ads.prefetch`\n\nBatch-request up to **10** ad contexts in a single call. Each item in the batch uses the same parameters as `ads.serve`.\n\n**Required:** `batch` (array, max 10 items — each requiring `conversationId`, `userKey`, `surface`)\n\n```javascript\nconst results = await callTool('ads.prefetch', {\n  batch: [\n    { conversationId: 'conv_1', userKey: 'user_456', surface: 'conversational', messages: [...] },\n    { conversationId: 'conv_2', userKey: 'user_456', surface: 'search',         messages: [...] }\n  ]\n});\n\n// results.ads            — array of ad objects (null where no ad matched)\n// results.prefetched_count — number of ads returned\n// results.truncated       — true if your batch exceeded the 10-item limit\n```\n\n---\n\n### `ads.diagnostics`\n\nRuns the full ad auction with debug output enabled. Uses the **same parameters** as `ads.serve` (same required fields: `conversationId`, `userKey`, `surface`).\n\nReturns the raw auction debug data including eligibility checks and match details.\n\n```javascript\nconst diag = await callTool('ads.diagnostics', {\n  conversationId: 'debug_abc123',\n  userKey:        'user_456',\n  surface:        'conversational',\n  messages: [\n    { role: \"user\", content: \"Tell me about electric vehicles\" }\n  ]\n});\n\nconsole.log(diag); // Full debug output from the auction engine\n```\n\n---\n\n## Ad Response Format\n\nWhen `ads.serve` returns a matched ad:\n\n```json\n{\n  \"ad\": {\n    \"id\": \"ad_abc123\",\n    \"title\": \"Product Title\",\n    \"content\": \"Description text\",\n    \"cta\": \"Learn More\",\n    \"click_url\": \"https://api.adgentek.ai/.../click?...\",\n    \"impression_url\": \"https://api.adgentek.ai/.../pixel.gif?...\",\n    \"render\": {\n      \"markdown\": \"## Title\\n\\nContent\\n\\n[CTA](click_url)\",\n      \"plain\": \"Title - Content - CTA\",\n      \"html\": \"<div>...</div>\"\n    }\n  },\n  \"targeting_scores\": { ... }\n}\n```\n\nWhen no ad matched:\n\n```json\n{\n  \"ad\": null,\n  \"reason\": \"no_eligible_ads\",\n  \"targeting_scores\": { ... }\n}\n```\n\n---\n\n## Tracking\n\nImpression and click tracking is handled via the URLs provided in every ad response. These work in any rendering context — browser, in-app webview, or embedded UI.\n\n- **Impressions**: Load `ad.impression_url` as a 1×1 pixel image when the ad is displayed\n- **Clicks**: Use `ad.click_url` as the CTA link href (signed redirect to advertiser destination)\n\n```html\n<!-- Impression pixel -->\n<img src=\"{ad.impression_url}\" width=\"1\" height=\"1\" style=\"display:none\" alt=\"\" />\n\n<!-- Click link -->\n<a href=\"{ad.click_url}\" target=\"_blank\" rel=\"noopener noreferrer\">{ad.cta}</a>\n```\n\nDo not modify or bypass these URLs — they are signed and time-limited.\n\n---\n\n## MCP Resources\n\nThe server exposes read-only documentation as MCP resources:\n\n| URI | Description |\n|-----|-------------|\n| `resource://adgentek/creative-guide` | Creative format guidelines and JS creative structure |\n| `resource://adgentek/integration-guide` | Platform setup and response format reference |\n| `resource://adgentek/tracking-spec` | Browser tracking requirements and fraud prevention |\n\n---\n\n## Full Ad Server — Bring Your Own Ads\n\nAdsMCP is not a demand source with an MCP interface bolted on. It is a full ad server.\n\nPublishers can:\n\n- **Use Adgentek's live demand** — we have established relationships across programmatic, performance, and direct demand channels, with more being added continuously\n- **Bring your own campaigns** — upload direct-sold advertiser deals and serve them through the same `ads.serve` call\n- **Layer in additional ad sources** — connect your own demand partners alongside Adgentek's, with automatic yield optimization across all of them\n\nYour inventory. Your demand relationships. One unified server.\n\n---\n\n## Privacy Architecture\n\nUser conversations are private. Raw conversation content is never shared with advertisers, demand partners, or third parties.\n\nAdsMCP transmits only derived signals to ad buyers — the minimum information required to match a relevant ad:\n\n| What advertisers receive | What stays in your app |\n|---|---|\n| IAB content category | Full conversation content |\n| Intent classification | User messages |\n| Keyword themes | Session context |\n\n---\n\n## Go Live\n\n1. **[Create your publisher account](https://app.adgentek.ai/publishers/auth)** and generate an API key\n2. **Create at least one AI Surface** in the publisher dashboard (Inventory → Surfaces)\n3. **Add the MCP config** to your AI application using the connection snippet above\n4. **Contact [hello@adgentek.ai](mailto:hello@adgentek.ai)** to verify your integration and activate live demand\n\n---\n\n## About Adgentek\n\nAdsMCP is built and operated by [Adgentek](https://adgentek.ai).\n\nAdgentek exists because AI apps are a fundamentally different kind of publisher — and they deserve ad infrastructure built for them, not retrofitted from the display web. Conversational interfaces have richer intent signals, longer engagement sessions, and none of the legacy constraints that shaped how traditional ad tech was built.\n\nAdgentek builds the ad monetization layer that is native to this environment: context-aware, privacy-safe, MCP-native, and designed to serve AI apps of any size — from a single-developer GPT to a multi-surface conversational platform. Our demand relationships span programmatic, direct, and performance channels, and publishers can layer in their own ad sources alongside ours.\n\nIf you are building an AI app and want ad revenue without building ad infrastructure, AdsMCP is what you are looking for.\n\n[hello@adgentek.ai](mailto:hello@adgentek.ai) — [adgentek.ai](https://adgentek.ai)\n",
  "bytes": 10072,
  "sha": "81c232fe24a649d879a9efa57bbd9c836f35b95f3caf33693274312d2cb8ff6b",
  "repo_slug": "adgentek/adsmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_adgentek_adsmcp_62df2bdc/readme"
}