mcpField
H
HPP x402 MCP Bridge

HPP x402 MCP Bridge

Local
docs.hpp.ioFinance0Updated 1w ago
DocsRepositoryVisit website

About HPP x402 MCP Bridge

HPP x402 MCP Bridge combines a stdio MCP bridge with the hpp-x402 CLI so agents can discover paid services and make HPP USDC.e payments per call. It supports spending caps and wallet-based payment delegation without API keys or manual signing.

Key features

  1. 01Search and inspect HPP service listings
  2. 02Pay for calls to HTTP, MCP and A2A services
  3. 03Pay x402 HTTP endpoints and A2A agents
  4. 04Set spending caps and use delegated wallets
  5. 05Manage the bridge with hpp-x402 CLI

Use cases

  1. 01Let an agent discover and pay for listed services
  2. 02Call x402 HTTP endpoints from an MCP host
  3. 03Pay another A2A agent for a message
  4. 04Limit agent payments with a wallet delegation

MCP support

An MCP host starts the bridge over stdio. Its tools support service discovery, descriptions and paid calls, with HPP wallet payments; an optional setting can proxy an upstream MCP server.

#payments#x402#usdc#agent-payments#hpp#crypto

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "x402-mcp-bridge": {
      "command": "npx",
      "args": [
        "-y",
        "@hpp-io/x402-mcp-bridge"
      ],
      "env": {
        "DELEGATE_PRIVATE_KEY": "<DELEGATE_PRIVATE_KEY>",
        "HPP_NETWORK": "<HPP_NETWORK>",
        "RESOURCE_SERVER_URL": "<RESOURCE_SERVER_URL>",
        "SAFE_ADDRESS": "<SAFE_ADDRESS>",
        "ALLOWANCE_MODULE_ADDRESS": "<ALLOWANCE_MODULE_ADDRESS>"
      }
    }
  }
}
Run commandnpx -y @hpp-io/x402-mcp-bridge
Environment variables to set
DELEGATE_PRIVATE_KEYSecretDelegate EOA private key used to sign payments. Auto-created in the OS keychain if unset.
HPP_NETWORKTarget network: eip155:181228 (HPP Sepolia, default) or eip155:190415 (HPP Mainnet).
RESOURCE_SERVER_URLOptional upstream MCP server to proxy. Omit to expose only the local tools.
SAFE_ADDRESSSafe address for governance (Safe) mode. Set together with ALLOWANCE_MODULE_ADDRESS.
ALLOWANCE_MODULE_ADDRESSSafe AllowanceModule address for governance (Safe) mode. Set together with SAFE_ADDRESS.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@hpp-io/x402-mcp-bridge0.1.23

Tools

9

Saved tool list · updated 3w ago

This tool takes no parameters.

Details

From the project README

@hpp-io/x402-mcp-bridge

npm MCP Registry License Node

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

# 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

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:

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
Pay from your HPP Smart Wallet instead

Rather than funding the agent's key, let it pay from your HPP Smart Wallet under a spending limit you set. In the wallet, open Agents → New, paste the agent's address (hpp-x402 wallet address), issue the delegation, then run the command the wallet shows — it is this, with the value filled in:

hpp-x402 install claude-code -n eip155:190415 --delegation 0x…

Run it on the machine where the agent's key lives. The value is checked against that key and the network before it is written, and again each time the bridge starts. The value can only be used by that key, within the limit, until it expires — but it does end up in your shell history, so treat it like a card with a cap. To stop the agent, revoke the delegation in the wallet.

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:

{ "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
ToolWhat it does
wallet_addressreport your wallet address (to fund it)
hpp_discoverlist/search the curated HPP directory (read-only)
hpp_describeone service's input args — schema + example (read-only)
hpp_callcall a discovered service (HTTP/MCP/A2A); pays via your wallet
x402_http_callpay + call any x402 HTTP endpoint
pay_a2a_agentpay + message another A2A agent

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

Key env (all optional)
VarNotes
DELEGATE_PRIVATE_KEYauto-created in the OS keychain if unset
HPP_NETWORKeip155:181228 Sepolia (default) / eip155:190415 Mainnet
RESOURCE_SERVER_URLproxy one upstream MCP server (omit = local tools only)
SAFE_ADDRESS + ALLOWANCE_MODULE_ADDRESSset both = Safe (governance) mode
HPP_PAYMENT_DELEGATIONERC-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. hpp-x402 install <host> --delegation <value> writes it. Checked against the key and the network at install and at boot (a value issued on the other network, revoked, or expired stops the bridge with the reason); without it such accepts are skipped

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

Related

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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.