{
  "markdown": "# @forgemeshlabs/x402-ads-mcp\n\n[![M8ven Score](https://m8ven.ai/badge/mcp/forgemeshlabs-x402-ads-mcp-lwf9ka)](https://m8ven.ai/mcp/forgemeshlabs-x402-ads-mcp-lwf9ka)\n\n**Install one middleware. Monetize unused 402 responses with recommendations, discovery, and machine commerce analytics.**\n\nThis is the MCP side of that network: what autonomous agents probe, want, and abandon across the x402 ecosystem — as tools for your agent.\n\nWraps the [ForgeMesh x402 Ads & Intent Network](https://ads.forgemesh.io). Paid tools settle per call in USDC on Base mainnet over the [x402 protocol](https://x402.org) — no account, no API key; your wallet is the login. Publishers get reports on their own services **free**.\n\n## Install\n\n```json\n{\n  \"mcpServers\": {\n    \"intent\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@forgemeshlabs/x402-ads-mcp\"],\n      \"env\": {\n        \"WALLET_PRIVATE_KEY\": \"0x... (optional — enables paid analytics)\",\n        \"X402_ADS_PUBLISHER_KEY\": \"pub_... (optional — free reports on your own services)\"\n      }\n    }\n  }\n}\n```\n\nBoth env vars are optional. With neither set, free tools work fully and paid tools return the x402 payment challenge (price, network, payTo) instead of settling — useful for inspection before spending anything.\n\n## Bonus: one-command publisher registration\n\nThis package doubles as the signup CLI for API operators (no MCP client needed):\n\n```bash\n# read the terms first: https://ads.forgemesh.io/terms\nWALLET_PRIVATE_KEY=0xYOUR_WALLET npx -y @forgemeshlabs/x402-ads-mcp register \\\n  --url https://api.your-service.com --accept-terms\n```\n\nOne $0.10 USDC payment on Base; the paying wallet becomes your identity and your publisher key is printed once. Invalid requests are rejected **before** payment — you can't pay for a doomed registration.\n\n## Tools\n\n| Tool | Price | What it returns |\n|---|---|---|\n| `get_network_counters` | free | Live network totals: 402s observed, agent-class requests, recommendations served |\n| `preview_recommendations` | free | The exact recommendations block the middleware injects into a 402 |\n| `get_terms` | free | Canonical terms + complete data-collection disclosure |\n| `get_network_stats` | $0.005 | Network totals + monitor/indexer/agent classification split |\n| `get_intent_trends` | $0.01 | Top endpoints & categories autonomous agents request |\n| `get_category_demand` | $0.02 | Demand depth for one category: volume, buyer share, price points |\n| `get_intent_report` | $0.05 / **free*** | Why-agents-didn't-buy funnel for one service |\n\n\\* `get_intent_report` is free with `X402_ADS_PUBLISHER_KEY` for services you contribute events to — the data co-op rule: your own data is free, forever.\n\n## Environment\n\n| Variable | Required | Purpose |\n|---|---|---|\n| `WALLET_PRIVATE_KEY` | no | Base mainnet wallet holding USDC; enables automatic settlement of paid tools |\n| `X402_ADS_PUBLISHER_KEY` | no | Publisher key from ads.forgemesh.io; free lane for your own reports |\n| `X402_ADS_BASE_URL` | no | Override the network base URL (default `https://ads.forgemesh.io`) |\n| `BASE_RPC_URL` | no | Override the Base RPC (default `https://mainnet.base.org`) |\n\nUse a dedicated hot wallet holding only small working balances. The key never leaves your machine — payments are signed locally (EIP-3009) and settle on-chain.\n\nReady-made configs live in [`examples/`](./examples): a Claude Desktop `mcpServers` block and a commented env-var template.\n\n## Testing (safe by construction)\n\n```bash\nnpm test                # smoke: MCP boots over stdio and lists its 7 tools\nnpm run test:free       # free tools against the live network\nnpm run test:challenge  # every paid tool returns an x402 challenge — no wallet, nothing can spend\nnpm run test:all        # all of the above\n```\n\nNo test settles a payment. The challenge test deletes the payment env vars before loading, so it cannot move funds even if your shell has a wallet configured.\n\n## The network in one sentence\n\n**We measure machine commerce, not API content** — publishers running the [`@forgemeshlabs/x402-ads`](https://www.npmjs.com/package/@forgemeshlabs/x402-ads) middleware contribute anonymized 402 probe metadata; this MCP sells the aggregate demand signal back to agents and builders.\n\nFull disclosure of what publishers send (and never send): https://ads.forgemesh.io/terms\n\n## License\n\nMIT © ForgeMesh\n",
  "bytes": 4349,
  "sha": "d294715ea692adb02d9869db22e3ce093301f9262cbb7dc4152417428e9efaf9",
  "repo_slug": "forgemeshlabs/x402-ads-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_forgemeshlabs_x402_ads_mcp_cdba7125/readme"
}