PayAgent — an MCP server that gives AI agents a wallet

An MCP server (Streamable HTTP, MCP spec 2025-11-25) that lets AI agents pay for metered web APIs per call, without a human in the loop. Built for the Alexa+ track of the Amazon Developer Hackathon (Build, Ship, Shape). Integrates with Alexa+ through the Alexa+ for Builders MCP toolkit.

The problem

AI agents can browse, reason, and act, but they cannot pay. Every metered API on the web expects a human with a credit card. PayAgent closes that gap: the agent holds its own USDC wallet and settles x402 micropayments autonomously, inside the spending limits its owner sets.

Related MCP server: x402 Micropayments MCP

Tools

Safety bounds: only x402 v2 exact challenges are honored; per-call spend is capped (default $1, hard cap $100); only http(s) URLs; private/loopback hosts are blocked unless ALLOW_PRIVATE_HOSTS=true; 15s request timeout.

Run it

npm install
npm run build

# Terminal 1: stub x402 seller (local demo endpoint, $0.05 per call)
node dist/examples/paid-endpoint-stub.js

# Terminal 2: the MCP server (Streamable HTTP on :3001/mcp)
ALLOW_PRIVATE_HOSTS=true node dist/src/server.js

# Terminal 3: demo MCP client (connects like any Alexa+/MCP agent would)
node dist/examples/demo-client.js

Expected: the client lists both tools, wallet_info shows the agent address, and x402_fetch returns PAID $0.050000 USDC ... HTTP 200 with the seller's data — the full 402 → sign → 200 loop, negotiated over MCP spec 2025-11-25.

Env

Copy .env.example to .env to configure.

How it works

MCP client (agent) --Streamable HTTP--> PayAgent --HTTPS--> paywalled API
                                                402 challenge
                                          <-- x402 v2 (price, payTo)
                                          EIP-3009 sign (agent wallet)
                                          PAYMENT-SIGNATURE -->
                                                        <-- 200 + data

The x402 buyer logic (src/x402buyer.ts) is adapted from our production-tested CRE x402 gateway: same EIP-3009 domain, same PAYMENT-SIGNATURE (v2) header format.

Layout

src/
  server.ts      # McpServer, tool registrations, Streamable HTTP bridge
  x402buyer.ts   # x402 v2 buyer: challenge parsing, EIP-3009 signing, wallet info
  x402verify.ts  # x402 v2 seller-side verification (used by the stub)
examples/
  paid-endpoint-stub.ts  # local $0.05/query x402 seller for demos
  demo-client.ts         # MCP client driving the full paid-fetch flow

License

MIT. See LICENSE.