io.github.forgemeshlabs/x402-ads-mcp
x402 ad recommendations, intent analytics, and machine-commerce demand reports.
Open source Open in the app JSON README (API)
About
x402 ad recommendations, intent analytics, and machine-commerce demand reports.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- forgemeshlabs
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.2
- Open pull requests
- 1
- Last push
- 2026-09-01T18:41:58Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 03:02:48
- Updated
- 2026-09-01 19:00:10
- Origin id
io.github.forgemeshlabs/x402-ads-mcp
README
# @forgemeshlabs/x402-ads-mcp
[](https://m8ven.ai/mcp/forgemeshlabs-x402-ads-mcp-lwf9ka)
**Install one middleware. Monetize unused 402 responses with recommendations, discovery, and machine commerce analytics.**
This is the MCP side of that network: what autonomous agents probe, want, and abandon across the x402 ecosystem — as tools for your agent.
Wraps 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**.
## Install
```json
{
"mcpServers": {
"intent": {
"command": "npx",
"args": ["-y", "@forgemeshlabs/x402-ads-mcp"],
"env": {
"WALLET_PRIVATE_KEY": "0x... (optional — enables paid analytics)",
"X402_ADS_PUBLISHER_KEY": "pub_... (optional — free reports on your own services)"
}
}
}
}
```
Both 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.
## Bonus: one-command publisher registration
This package doubles as the signup CLI for API operators (no MCP client needed):
```bash
# read the terms first: https://ads.forgemesh.io/terms
WALLET_PRIVATE_KEY=0xYOUR_WALLET npx -y @forgemeshlabs/x402-ads-mcp register \
--url https://api.your-service.com --accept-terms
```
One $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.
## Tools
| Tool | Price | What it returns |
|---|---|---|
| `get_network_counters` | free | Live network totals: 402s observed, agent-class requests, recommendations served |
| `preview_recommendations` | free | The exact recommendations block the middleware injects into a 402 |
| `get_terms` | free | Canonical terms + complete data-collection disclosure |
| `get_network_stats` | $0.005 | Network totals + monitor/indexer/agent classification split |
| `get_intent_trends` | $0.01 | Top endpoints & categories autonomous agents request |
| `get_category_demand` | $0.02 | Demand depth for one category: volume, buyer share, price points |
| `get_intent_report` | $0.05 / **free*** | Why-agents-didn't-buy funnel for one service |
\* `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.
## Environment
| Variable | Required | Purpose |
|---|---|---|
| `WALLET_PRIVATE_KEY` | no | Base mainnet wallet holding USDC; enables automatic settlement of paid tools |
| `X402_ADS_PUBLISHER_KEY` | no | Publisher key from ads.forgemesh.io; free lane for your own reports |
| `X402_ADS_BASE_URL` | no | Override the network base URL (default `https://ads.forgemesh.io`) |
| `BASE_RPC_URL` | no | Override the Base RPC (default `https://mainnet.base.org`) |
Use 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.
Ready-made configs live in [`examples/`](./examples): a Claude Desktop `mcpServers` block and a commented env-var template.
## Testing (safe by construction)
```bash
npm test # smoke: MCP boots over stdio and lists its 7 tools
npm run test:free # free tools against the live network
npm run test:challenge # every paid tool returns an x402 challenge — no wallet, nothing can spend
npm run test:all # all of the above
```
No 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.
## The network in one sentence
**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.
Full disclosure of what publishers send (and never send): https://ads.forgemesh.io/terms
## License
MIT © ForgeMesh