@x402-market/mcp-server

@x402-market/mcp-server

An MCP server that lets AI agents discover and pay for HTTP APIs autonomously via the x402 protocol on Base mainnet.

Status: stable. End-to-end paid flow verified on Base mainnet (real 0.01 USDC tx settled, upstream proxied, billing reconciled). Auto-judged refund flow verified the same way. See CHANGELOG.md for the gate.

Drop it into Claude Desktop / Cursor / any MCP host and the model gets a handful of tools: browse the marketplace catalog, inspect a listing, invoke a paid endpoint with one tool call (pay_and_call), and claim refunds on failed calls (claim_refund) — the server handles the 402 challenge, the on-chain USDC transfer, and the retry transparently.

Why

Most "AI tools" cost money to operate but agents can't pay. They're stuck calling free or hard-coded APIs with API keys some human had to provision. x402 turns that around: every endpoint is reachable by paying USDC per call, no signup. This MCP server bridges that to the agent runtime.

Backed by the live marketplace at https://x402-market-api.lien-studio-akiyama.workers.dev.

Install

npm install -g @x402-market/mcp-server
# or run on demand without installing:
npx @x402-market/mcp-server

Requires Node.js >= 20.

Tools

Tool	What it does
list_catalog	List active marketplace listings (optional category filter).
get_listing	Full schema, examples, and price for one listing slug.
pay_and_call	Recommended. End-to-end: discover price → send USDC → retry → return upstream response.
claim_refund	Request an auto-judged refund on a previous paid call (failed upstream / latency >30s).
call_api_unpaid	Low-level: fetch the 402 challenge body without paying.
call_api_paid	Low-level: invoke with a manually-supplied tx hash.

Use pay_and_call for normal operation. The two call_api_* tools are kept for debugging / hand-rolled flows.

Claude Desktop setup

Edit claude_desktop_config.json (location depends on OS — see Claude Desktop docs):

{
  "mcpServers": {
    "x402-market": {
      "command": "npx",
      "args": ["-y", "@x402-market/mcp-server"],
      "env": {
        "MARKET_API_URL": "https://x402-market-api.lien-studio-akiyama.workers.dev",
        "MCP_BUYER_PRIVATE_KEY": "0x...",
        "BASE_RPC_URL": "https://base-mainnet.g.alchemy.com/v2/<YOUR_KEY>",
        "BASE_CHAIN_ID": "8453",
        "MCP_MAX_PRICE": "1.0"
      }
    }
  }
}

MCP_BUYER_PRIVATE_KEY is a wallet you fund with a small USDC budget. Without it, the read-only tools work but pay_and_call returns a setup error.

Restart Claude Desktop. The model now has the five tools above.

Cursor setup

~/.cursor/mcp.json:

{
  "mcpServers": {
    "x402-market": {
      "command": "npx",
      "args": ["-y", "@x402-market/mcp-server"],
      "env": {
        "MARKET_API_URL": "https://x402-market-api.lien-studio-akiyama.workers.dev",
        "MCP_BUYER_PRIVATE_KEY": "0x...",
        "BASE_RPC_URL": "https://base-mainnet.g.alchemy.com/v2/<YOUR_KEY>",
        "BASE_CHAIN_ID": "8453"
      }
    }
  }
}

Sample listing: test-echo

A demo listing on the live marketplace. 0.01 USDC per call, returns whatever JSON you POST to it.

// pay_and_call input
{
  "seller_slug": "seller-4068b8fc",
  "listing_slug": "test-echo",
  "method": "POST",
  "body": { "hello": "world", "from": "claude" }
}

// pay_and_call output (paraphrased; real output is a single text content block)
{
  "status": 200,
  "data": {
    "request_id": "...",
    "timestamp": "2026-05-02T...Z",
    "method": "POST",
    "echoed": { "hello": "world", "from": "claude" }
  },
  "tx_hash": "0x...",
  "price_paid_usdc": "0.01",
  "pay_to": "0x4068b8Fc01647eCFFb5873a91578721b4FE7a9eE"
}

The agent never has to think about 402 challenges or USDC mechanics. One tool, one call.

Funding the buyer wallet

pay_and_call spends from MCP_BUYER_PRIVATE_KEY. Use a wallet separate from your main one holding only the e2e budget:

• Create a fresh EOA (MetaMask → Add account).
• Fund on Base mainnet:
  • ~0.0005 ETH for gas (bridge via https://bridge.base.org/).
  • A few USDC for calls.
  • USDC contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.
• Drop the private key into your MCP host config (treat it like an API key).
• MCP_MAX_PRICE (default 1.0) is your circuit breaker — even a malicious listing returning a 402 with a huge amount won't drain you above the cap.

Env vars

Var	Default	Purpose
MARKET_API_URL	https://x402-market-api.lien-studio-akiyama.workers.dev	Marketplace API base URL
MCP_BUYER_PRIVATE_KEY	(none)	Funded wallet for pay_and_call
BASE_RPC_URL	https://mainnet.base.org	Base RPC endpoint (Alchemy/QuickNode for higher rate limits)
BASE_CHAIN_ID	8453	8453 = Base mainnet (default). 84532 = Base Sepolia.
MCP_MAX_PRICE	1.0	Hard cap per call (USDC)

Defaults match where the live listings actually run (Base mainnet). To exercise the server against Sepolia testnet listings, set both BASE_CHAIN_ID=84532 and BASE_RPC_URL=https://sepolia.base.org.

Architecture

[ Claude / Cursor ] -- MCP stdio --> [ this server ]
                                          |
                                          | HTTP + viem
                                          v
                          [ x402-market API on Cloudflare Workers ]
                                          |
                                          | x402 challenge / verify
                                          v
                                    [ seller's API ]

The MCP server stays small (one bundled JS file, ~250 KB gzipped). All payment logic lives in the marketplace API — this is a thin tool adapter.

Repository

https://github.com/AsaiShota/x402-market — full monorepo with the API server, dashboard, payout cron, and Python SDK.

License

MIT