HPP x402 MCP Bridge

Official

by hpp-io · TypeScript

MCP bridge for autonomous x402 payments in HPP USDC.e — discover and pay for services per call.

io.github.hpp-io/x402-mcp-bridge MCP Server

This MCP bridge provides an agent payment rail for HPP in USDC.e. It supports autonomous x402 payments and enables discovery and payment for services per call. It is distributed as a stdio MCP bridge together with the hpp-x402 CLI.

🛠️ Key Features

Autonomous x402 payments in HPP USDC.e
Service discovery and payments “per call”
stdio-based MCP bridge
hpp-x402 CLI integration
Listed in the MCP Registry

🚀 Use Cases

Enable agent-driven payments via MCP
Discover and pay for services dynamically per call
Use x402 payment flows through HPP in USDC.e

⚡ Developer Benefits

Node.js compatible (node >= 20)
Apache-2.0 licensed package
Consumable via MCP tooling alongside hpp-x402 CLI

⚠️ Limitations

Source material does not specify supported MCP tools, transport beyond stdio, or authentication/permissions details.

Topics

agent-paymentshppmcpmcp-serverx402

README.md4 KBView on GitHub

@hpp-io/x402-mcp-bridge

The agent payment rail for HPP. A stdio MCP bridge + the hpp-x402 CLI that let Claude Desktop / Claude Code / Cursor / Windsurf / OpenClaw make autonomous HPP USDC.e payments over x402 — discover paid services, pay per call, within a spend cap. No API keys, no manual signing.

📖 Full documentation

hpp-io/x402-tools — the complete manual: how it works, every command, buyer and seller flows, payment schemes (exact / upto), wallet modes, and troubleshooting. This README is a quick reference.

Install

bash

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/hpp-io/x402-tools/main/install/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/hpp-io/x402-tools/main/install/install.ps1 | iex
# …or npm
npm install -g @hpp-io/x402-mcp-bridge

Needs Node 20+. On a headless box (no OS keychain) use setup --print-key — see the manual.

Quick start

bash

hpp-x402 setup --install claude-code   # create a wallet + register into your host
hpp-x402 fund                          # where to send USDC.e (gasless, no native gas)
hpp-x402 status                        # confirm it's wired

Restart your host and your agent can discover and pay for services. Browse and pay from the terminal too:

bash

hpp-x402 discover "price prediction"               # semantic search; your network only
hpp-x402 describe <id>                             # input args (schema + example) — no payment
hpp-x402 call <url-or-id> --body '{"hi":"there"}'  # pay + call — a URL, or an id from discover

Full command reference, selling (serve), schemes, and Safe mode → the manual.

Use it from an MCP host

The host spawns the bridge over stdio. A bare entry boots zero-config on HPP Sepolia with an auto-created keychain wallet:

jsonc

{ "mcpServers": { "hpp-x402": {
  "command": "npx", "args": ["-y", "@hpp-io/x402-mcp-bridge"]
} } }

hpp-x402 install <host> writes this for you. Note: a bare npx @hpp-io/x402-mcp-bridge runs the MCP server (what the host wants) — for the CLI use npx -y -p @hpp-io/x402-mcp-bridge hpp-x402 <command>.

Host-facing tools

Tool	What it does
`wallet_address`	report your wallet address (to fund it)
`hpp_discover`	list/search the curated HPP directory (read-only)
`hpp_describe`	one service's input args — schema + example (read-only)
`hpp_call`	call a discovered service (HTTP/MCP/A2A); pays via your wallet
`x402_http_call`	pay + call any x402 HTTP endpoint
`pay_a2a_agent`	pay + message another A2A agent

Every paid call stays within your spend cap; discovery never holds funds or sees your keys.

Key env (all optional)

Var	Notes
`DELEGATE_PRIVATE_KEY`	auto-created in the OS keychain if unset
`HPP_NETWORK`	`eip155:181228` Sepolia (default) / `eip155:190415` Mainnet
`RESOURCE_SERVER_URL`	proxy one upstream MCP server (omit = local tools only)
`SAFE_ADDRESS` + `ALLOWANCE_MODULE_ADDRESS`	set both = Safe (governance) mode
`HPP_PAYMENT_DELEGATION`	ERC-7710 payment delegation a wallet granted to this key: pays `erc7710` accepts from the user's smart account under on-chain caps — this key needs no USDC.e. Validated at boot; without it such accepts are skipped

Full environment reference + Safe/governance setup are in the manual.

Building an agent / SDK integration (LangChain, OpenAI function-calling, AgentKit, A2A)? See the runnable gallery → hpp-io/hpp-x402-agent-sample

License

Apache-2.0

Install

Configuration

Environment variables

DELEGATE_PRIVATE_KEYsecret

Delegate EOA private key used to sign payments. Auto-created in the OS keychain if unset.

HPP_NETWORK

Target network: eip155:181228 (HPP Sepolia, default) or eip155:190415 (HPP Mainnet).

RESOURCE_SERVER_URL

Optional upstream MCP server to proxy. Omit to expose only the local tools.

SAFE_ADDRESS

Safe address for governance (Safe) mode. Set together with ALLOWANCE_MODULE_ADDRESS.

ALLOWANCE_MODULE_ADDRESS

Safe AllowanceModule address for governance (Safe) mode. Set together with SAFE_ADDRESS.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "x402-mcp-bridge": {
      "command": "npx",
      "args": [
        "-y",
        "@hpp-io/x402-mcp-bridge@0.1.22"
      ],
      "env": {
        "DELEGATE_PRIVATE_KEY": "<YOUR_DELEGATE_PRIVATE_KEY>",
        "HPP_NETWORK": "<YOUR_HPP_NETWORK>",
        "RESOURCE_SERVER_URL": "<YOUR_RESOURCE_SERVER_URL>",
        "SAFE_ADDRESS": "<YOUR_SAFE_ADDRESS>",
        "ALLOWANCE_MODULE_ADDRESS": "<YOUR_ALLOWANCE_MODULE_ADDRESS>"
      }
    }
  }
}

io.github.hpp-io/x402-mcp-bridge MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

@hpp-io/x402-mcp-bridge

📖 Full documentation

Install

Quick start

Use it from an MCP host

Host-facing tools

Key env (all optional)

Related

License

Install

Configuration

Related servers