How do I install X402 Ads?

X402 Ads is a local plugin. Install it using npm package: @forgemeshlabs/x402-ads-mcp and add the generated configuration snippet to your AI app's MCP config file. Then restart your AI app.

Is X402 Ads safe to use?

Yes. X402 Ads passed MCP Marketplace's automated security scan with a score of 10/10 (low risk). Every server on MCP Marketplace is security-scanned before it's listed; see the full security report on this page for the findings and permissions.

What credentials does X402 Ads need?

X402 Ads requires the following credentials or environment variables: WALLET_PRIVATE_KEY, X402_ADS_PUBLISHER_KEY. You can find setup instructions on the server detail page.

What AI apps work with X402 Ads?

X402 Ads uses the Model Context Protocol (MCP) and works with any MCP-compatible AI app, including Claude, ChatGPT / Codex, Gemini, Copilot, Cursor, and more.

Back to Browse

X402 Ads MCP Server

by ForgeMesh

Developer ToolsLow Risk10.0Local

Free

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

About

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

Security Report

10.0

Low Risk10.0Low Risk

Valid MCP server (2 strong, 2 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry. Trust signals: trusted author (48/50 approved).

7 files analyzed · 1 issue found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

env_vars

Check that this permission is expected for this type of plugin.

HTTP Network Access

Connects to external APIs or services over the internet.

Shell Command Execution

Runs commands on your machine. Be cautious — only use if you trust this plugin.

What You'll Need

Set these up before or after installing:

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

Environment variable: WALLET_PRIVATE_KEY

Optional publisher key from ads.forgemesh.io. Makes get_intent_report free for your registered services.Required

Environment variable: X402_ADS_PUBLISHER_KEY

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "io-github-forgemeshlabs-x402-ads-mcp": {
      "env": {
        "BASE_RPC_URL": "your-base-rpc-url-here",
        "X402_ADS_BASE_URL": "your-x402-ads-base-url-here",
        "WALLET_PRIVATE_KEY": "your-wallet-private-key-here",
        "X402_ADS_PUBLISHER_KEY": "your-x402-ads-publisher-key-here"
      },
      "args": [
        "-y",
        "@forgemeshlabs/x402-ads-mcp"
      ],
      "command": "npx"
    }
  }
}

Documentation

View on GitHub

From the project's GitHub README.

@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

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_MAX_PRICE_USD`	no	Per-call price cap in USD; can only LOWER the built-in cap ($0.05, or $0.10 for `register`)
`X402_SESSION_BUDGET_USD`	no	Cumulative 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