Overview

wallet-mcp-server (published as @polymitapay/mcp) is an MCP server you install into your own AI agent so it can search the PolyPay catalog and auto-pay for tools over x402, on XRPL — without you writing any payment integration code.

It runs entirely on your machine. That's the point: it's non-custodial, nothing about it ever touches a server you don't control. At startup it:

1. fetches PolyPay's public catalog (GET /v1/catalog, no account needed),
2. opens one auto-paying MCP connection per approved provider, using @x402/mcp's x402MCPClient (this is what handles the HTTP 402 → pay → retry flow for you),
3. re-exposes all of it over its own stdio MCP server, to your agent.

Two tools, not one per provider

However large the catalog gets, your agent only ever sees two tools:

• polymitapay_search — semantic search over every real tool across every provider, matching by meaning rather than requiring exact keyword overlap (see the catalog API for how). Returns matches with their price.
• polymitapay_call — invokes a tool found via polymitapay_search. Payment is signed and settled automatically with the wallet you configured, no approval popups.

This is deliberate. If the catalog were exposed one tool per real provider tool, every agent turn's context would carry the full list of names and schemas — expensive, and it hurts tool selection as the catalog grows. Search-then-call keeps your agent's context small no matter how many providers exist.

Non-custodial, by design

You supply a wallet seed (POLYPAY_WALLET_SEED) when you install. It's used to sign payments locally and is never sent anywhere except as part of a signed XRPL transaction. See Install to get one, and the security note there before you use a real (mainnet) wallet.