English Français العربية

io.github.forgemeshlabs/x402-ads-mcp

Official registry Marketing and sales

x402 ad recommendations, intent analytics, and machine-commerce demand reports.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @forgemeshlabs/x402-ads-mcp
Claude Code 
claude mcp add x402-ads-mcp -e 'WALLET_PRIVATE_KEY=<your wallet_private_key>' -e 'X402_ADS_PUBLISHER_KEY=<your x402_ads_publisher_key>' -- npx -y @forgemeshlabs/x402-ads-mcp@0.2.5
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "x402-ads-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@forgemeshlabs/x402-ads-mcp@0.2.5"
            ],
            "env": {
                "WALLET_PRIVATE_KEY": "<your wallet_private_key>",
                "X402_ADS_PUBLISHER_KEY": "<your x402_ads_publisher_key>"
            }
        }
    }
}

Environment variables

  • WALLET_PRIVATE_KEY secret Optional dedicated low-balance Base wallet private key for settling paid x402 analytics calls. Without it, paid tools return the x402 payment challenge instead of settling.
  • X402_ADS_PUBLISHER_KEY secret Optional publisher key from ads.forgemesh.io. Makes get_intent_report free for your registered services.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. @forgemeshlabs/x402-ads-mcp
  2. Install
  3. Bonus: one-command publisher registration
  4. Tools
  5. Environment
  6. Testing (safe by construction)
  7. The network in one sentence
  8. License

@forgemeshlabs/x402-ads-mcp

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. Paid tools settle per call in USDC on Base mainnet over the x402 protocol — no account, no API key; your wallet is the login. Publishers get reports on their own services free.

Install

{
  "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):

# 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

ToolPriceWhat it returns
get_network_countersfreeLive network totals: 402s observed, agent-class requests, recommendations served
preview_recommendationsfreeThe exact recommendations block the middleware injects into a 402
get_termsfreeCanonical terms + complete data-collection disclosure
get_network_stats$0.005Network totals + monitor/indexer/agent classification split
get_intent_trends$0.01Top endpoints & categories autonomous agents request
get_category_demand$0.02Demand 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

VariableRequiredPurpose
WALLET_PRIVATE_KEYnoBase mainnet wallet holding USDC; enables automatic settlement of paid tools
X402_ADS_PUBLISHER_KEYnoPublisher key from ads.forgemesh.io; free lane for your own reports
X402_MAX_PRICE_USDnoPer-call price cap in USD; can only LOWER the built-in cap ($0.05, or $0.10 for register)
X402_SESSION_BUDGET_USDnoCumulative cap per process; can only LOWER the built-in $10

The backend URL is fixed to https://ads.forgemesh.io (the publisher key is only ever sent there). The server refuses to sign for any payee other than the ForgeMesh Ads wallet, any network other than Base mainnet, any asset other than USDC, or any amount over the cap. Use a dedicated, low-balance wallet. The key never leaves your machine — payments are signed locally (EIP-3009) and settle on-chain.

Ready-made configs live in examples/: a Claude Desktop mcpServers block and a commented env-var template.

Testing (safe by construction)

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

Frequently asked questions

What is io.github.forgemeshlabs/x402-ads-mcp?

x402 ad recommendations, intent analytics, and machine-commerce demand reports.

How do I install io.github.forgemeshlabs/x402-ads-mcp?

It runs on your machine. In Claude Code: claude mcp add x402-ads-mcp -e 'WALLET_PRIVATE_KEY=<your wallet_private_key>' -e 'X402_ADS_PUBLISHER_KEY=<your x402_ads_publisher_key>' -- npx -y @forgemeshlabs/x402-ads-mcp@0.2.5. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.forgemeshlabs/x402-ads-mcp need an API key?

Yes. It expects WALLET_PRIVATE_KEY, X402_ADS_PUBLISHER_KEY, which you set in its configuration.

Is io.github.forgemeshlabs/x402-ads-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.forgemeshlabs/x402-ads-mcp?

It is published by forgemeshlabs. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.