x402-mcp

A Model Context Protocol server that turns any AI assistant into an autonomous economic agent on the x402 network. Search the live bazaar for paid services, read an endpoint's price before committing money, and pay_and_call any x402 service in USDC — settled on Solana with your own key, never a custodial wallet.

This is the buyer side of the three.ws agent economy. The payment dance and Solana exact-scheme signing are handled by the real @x402/* libraries — nothing is mocked.

Install

npm install @three-ws/x402-mcp

Or run with npx:

SOLANA_SECRET_KEY=<base58> npx @three-ws/x402-mcp

Related MCP server: BotWallet MCP Server

Quick start

Claude Code, one line:

claude mcp add x402 --env SOLANA_SECRET_KEY=<base58> -- npx -y @three-ws/x402-mcp

Claude Desktop / Cursor (claude_desktop_config.json or mcp.json):

{
	"mcpServers": {
		"x402": {
			"command": "npx",
			"args": ["-y", "@three-ws/x402-mcp"],
			"env": {
				"SOLANA_SECRET_KEY": "<base58 secret of the wallet that holds USDC>",
				"SOLANA_RPC_URL": "https://your-rpc-provider",
				"MAX_PAY_USD": "1"
			}
		}
	}
}

SOLANA_SECRET_KEY is only needed to spend (pay_and_call, and x402_wallet defaulting to your wallet). find_services and inspect_endpoint work with no key.

Tools

Safety

pay_and_call carries destructiveHint: true, so annotation-aware clients (Claude Code, Claude Desktop, Cursor) prompt before running it. Beyond the client hint, every payment is bounded server-side: it probes the 402 first and refuses if the price exceeds max_usd or MAX_PAY_USD (default $1) before any money moves, and with REQUIRE_CONFIRM on (default) the call refuses until re-issued with confirm: true. Only the Solana (solana:*) exact-scheme requirement is settled — with the key you control.

Input parameters

x402_wallet — address (optional base58; defaults to the signer wallet).

find_services — query (required), type (http | mcp, default http), network (CAIP-2 filter), max_price_usdc, limit (1–100).

inspect_endpoint — url (required), method (GET | POST), body (object).

pay_and_call: url (required), method (GET | POST), body (object), max_usd (lowers the cap for this call), secret (per-call signer override), confirm (must be true when REQUIRE_CONFIRM is on), session_token, token, idempotency_key.

It has two settlement modes:

• Self-custodial (default). Signs with SOLANA_SECRET_KEY, or the per-call secret. You hold the key.

• Session-governed. Pass session_token, a three.ws Payment Session token, and the platform wallet signs on your behalf while enforcing that session's budget, host allowlist, and per-transaction cap. No private key needed. Solana USDC and Base USDC sessions are both supported, and secret and token are ignored in this mode.

token selects the settlement asset: usdc (default), or three for the $THREE platform token when the endpoint advertises it. idempotency_key deduplicates a call, which is recommended with session_token so a retry cannot double-charge.

Example

// inspect_endpoint — what does it cost? (no payment)
> { "url": "https://three.ws/api/x402/vanity?prefix=ab" }
{
  "ok": true, "paid": true,
  "accepts": [
    { "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "asset": "EPjFW…", "price": 50000 }
  ],
  "payable_with_this_wallet": true
}

// pay_and_call — confirm:true required by default
> { "url": "https://three.ws/api/x402/vanity?prefix=ab", "confirm": true }
{ "ok": true, "paid": true, "payer": "Gx5E…", "price_usd": 0.05, "settlement": { … }, "result": { … } }

Examples

Runnable, no-payment examples live in examples/:

node examples/list-tools.mjs      # every tool with its full input schema
node examples/inspect-price.mjs   # find_services + inspect_endpoint on live data

Both spawn this server over stdio and hit the real bazaar. Neither reads a key or calls pay_and_call, so nothing is signed and nothing is spent. See examples/README.md for expected output.

Requirements

• Node.js >= 20.

• A Solana mainnet RPC endpoint (https; only http://localhost is allowed for dev). Public cluster works for reads; bring your own for payment traffic.

• To pay: a Solana wallet holding USDC, as a base58 SOLANA_SECRET_KEY (or per-call secret).

Environment variables

Links

• Homepage: https://three.ws

• MCP catalog: https://three.ws/docs/mcp

• Changelog: https://three.ws/changelog

• Issues: https://github.com/nirholas/three.ws/issues

• License: Apache-2.0, see LICENSE

Support the project

If x402-payments-mcp saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/x402-payments-mcp and it has the context it needs.

More from the same author

• All repositories by nirholas: the full catalog, grouped by topic

• three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments

• Questions or ideas: open an issue or start a discussion

Contributors

Star history

Part of three.ws

three.ws is a platform for 3D AI agents with Solana wallets: avatars, a skill marketplace, x402 payments and more than seventy MCP servers. @three-ws/x402-mcp is one package from it.

• Documentation site: https://nirholas.github.io/x402-payments-mcp/

• npm: https://www.npmjs.com/package/@three-ws/x402-mcp

• Canonical source: https://github.com/nirholas/three.ws (this repository is a generated mirror of packages/x402-mcp)

• Agent-readable summary: llms.txt and AGENTS.md

• Issues and ideas: https://github.com/nirholas/x402-payments-mcp/issues