# @hpp-io/x402-mcp-bridge

[![npm](https://img.shields.io/npm/v/@hpp-io/x402-mcp-bridge?logo=npm)](https://www.npmjs.com/package/@hpp-io/x402-mcp-bridge)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-1f6feb)](https://registry.modelcontextprotocol.io/?q=x402-mcp-bridge)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](./LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D20-3c873a?logo=node.js)](https://nodejs.org)

> 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](https://x402.org) — discover paid services,
> pay per call, within a spend cap. No API keys, no manual signing.

## 📖 Full documentation

**[hpp-io/x402-tools](https://github.com/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](https://github.com/hpp-io/x402-tools#requirements).

## 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
```

### Pay from your HPP Smart Wallet instead

Rather than funding the agent's key, let it pay from your
[HPP Smart Wallet](https://docs.hpp.io/smart-accounts/pay-from-an-agent) 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:

```bash
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](https://github.com/hpp-io/x402-tools)**.

## 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 (per-call cap defaults to 1 USDC.e;
raise it with `wallet_set_limit`) and is paid only in allowlisted tokens;
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 |
| `HPP_X402_ALLOWED_ASSETS` | extra tokens the bridge may pay in (comma-separated addresses). By default only USDC.e (both networks) and HAC (Sepolia test token); a 402 priced in any other token is refused before signing |
| `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. `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](https://github.com/hpp-io/x402-tools).

## Related

Building an agent / SDK integration (LangChain, OpenAI function-calling, AgentKit,
A2A)? See the runnable gallery →
[hpp-io/hpp-x402-agent-sample](https://github.com/hpp-io/hpp-x402-agent-sample)

## License

Apache-2.0