a2a-x402-mcp-services

Production-oriented x402 v2 monetized MCP tools for real agent-to-agent (A2A) commerce.

• Authentic on-chain settlement (no mocks, no simulated payments)

• Fully compliant with the current x402 v2 specification (CAIP-2 networks, PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE headers, x402Version: 2, exact scheme)

• Official @x402/mcp + @x402/core + @x402/evm packages

• Bazaar-ready (tools are discoverable via facilitators that implement the Bazaar extension)

• Built against the live ecosystem gaps: operational utilities agents actually re-purchase

Current Paid Tools

All tools use the exact payment scheme and settle through a real facilitator.

Related MCP server: Agent Commerce Suite

x402 v2 Compliance Checklist

• x402Version: 2

• CAIP-2 network identifiers (eip155:84532 Base Sepolia default, eip155:8453 for mainnet)

• Official headers (PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE)

• Exact scheme via @x402/evm/exact

• Facilitator-based verify + settle (never self-settled in process)

• Bazaar extension metadata for MCP tool discovery

• Environment-driven payTo address (no hard-coded production wallets)

Quick Start (Testnet)

git clone https://github.com/Disseveru/a2a-x402-mcp-services.git
cd a2a-x402-mcp-services
npm install

# Required: receiving wallet (Base Sepolia)
export X402_PAY_TO_EVM=0xYourTestnetAddress

# Optional overrides
# export X402_NETWORK=eip155:84532
# export X402_FACILITATOR_URL=https://x402.org/facilitator
# export PORT=4022

npm run dev

Health check (free):

curl http://localhost:4022/health

Tool catalog (free):

curl http://localhost:4022/tools

MCP endpoint (paid):

POST http://localhost:4022/mcp

Use any x402 v2-aware MCP client (@x402/mcp client helpers, CDP-managed wallets, etc.). The first call to a paid tool will receive a proper 402; the client signs and retries with PAYMENT-SIGNATURE; the facilitator settles; the tool result is returned.

Moving to Mainnet

1. Set a mainnet receiving address:

   export X402_PAY_TO_EVM=0xYourMainnetAddress

2. Switch network:

   export X402_NETWORK=eip155:8453

3. Use a production facilitator (example – CDP):

   export X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402

   (Supply CDP credentials if the chosen facilitator requires them.)

4. Start the server. Real USDC will move.

Never run mainnet with a hot key that holds more than you are willing to lose.

Architecture

src/
  config.ts          – env-driven CAIP-2 + facilitator + payTo
  server.ts          – McpServer + official createPaymentWrapper (@x402/mcp)
  tools/
    definitions.ts   – paid tool implementations (real logic)
  index.ts           – Express host + Streamable HTTP MCP transport

Design Principles

1. No mocks – every paid path ends in a real facilitator settle call.

2. v2 only – no legacy X-PAYMENT headers or v1 network strings.

3. Operational utility – tools solve repeat-purchase agent problems (risk, normalization, facilitator selection).

4. Discoverable – Bazaar metadata is present so agents can find the tools without hard-coding URLs.

5. Operator safety – receiving address and network come exclusively from environment variables.

License

MIT