@hpp-io/x402-mcp-bridge

stdio MCP bridge that lets Claude Desktop / OpenClaw / other MCP hosts make autonomous HPP USDC.e payments via x402 — funds stay in a Safe, the bridge auto-tops up a delegate EOA within an on-chain spend cap (AllowanceModule).

What it is

The MCP host (Claude Desktop, OpenClaw, Cursor, …) doesn't know how to sign EIP-3009 payments. This bridge runs as a stdio subprocess that the host spawns, exposes itself as an MCP server to the host, and internally:

1. Connects upstream to a remote x402 MCP server (SSE / StreamableHTTP).
2. Forwards listTools / callTool between host and remote.
3. When the remote returns 402, the bridge:
   • Tops up the delegate EOA from the user's Safe via AllowanceModule.executeAllowanceTransfer (chain-enforced daily cap).
   • Signs EIP-3009 transferWithAuthorization with the delegate key.
   • Retries the call.

The host sees a normal MCP server and never deals with payment.

Install / use

// claude_desktop_config.json
{
  "mcpServers": {
    "hpp-x402": {
      "command": "npx",
      "args": ["-y", "@hpp-io/x402-mcp-bridge"],
      "env": {
        "DELEGATE_PRIVATE_KEY": "keychain://hpp-x402/delegate-default",
        "SAFE_ADDRESS": "0x...",
        "ALLOWANCE_MODULE_ADDRESS": "0x...",
        "USDCE_ADDRESS": "0x...",
        "RESOURCE_SERVER_URL": "https://your-x402-server/mcp/sse",
        "HPP_RPC_URL": "https://sepolia.hpp.io",
        "HPP_NETWORK": "eip155:181228"
      }
    }
  }
}

DELEGATE_PRIVATE_KEY accepts either form:

• keychain://hpp-x402/<account> — resolved via the OS keychain (macOS Keychain / Windows Credential Vault / Linux libsecret) at startup. Recommended — no plaintext key on disk.
• 0x[64 hex] — raw key. Fine for quickstart / development.

To populate the keychain entry, see Keychain CLI below.

Same config block works for OpenClaw and any other MCP host that supports stdio MCP servers. See examples/ for ready-to-merge JSON snippets and a local development guide for using the bridge before it's published to npm.

📖 First time? Walk through docs/SETUP.md — covers Safe deployment, OS keychain storage, and host registration step by step.

Pre-flight (one-time, on-chain)

Before the bridge can do anything, you need a Safe with USDC.e and an AllowanceModule entry that authorises a delegate EOA to pull from it:

1. Deploy / use an existing Safe at safe.hpp.io.
2. Send USDC.e to the Safe.
3. Enable the AllowanceModule on the Safe (one Safe transaction).
4. addDelegate(<delegate EOA>) and setAllowance(<delegate>, USDC.e, <daily cap>, 1440 minutes, 0) — one Safe transaction each (or batched via Safe's MultiSend).
5. Send a small amount of native ETH to the delegate EOA (it pays gas for executeAllowanceTransfer).

Verified end-to-end on HPP Sepolia 2026-05-06 — the chain enforces the daily cap, and deleteAllowance instantly blocks future top-ups.

Keychain CLI

hpp-x402-keychain stores the delegate private key in the OS keychain so it never lives in .env / claude_desktop_config.json plaintext.

# Store an existing key (prompts, no echo):
npx -y -p @hpp-io/x402-mcp-bridge hpp-x402-keychain set
# → asks for "0x..." and prints the URI + derived address

# Or generate a fresh delegate + store it in one shot:
npx -y -p @hpp-io/x402-mcp-bridge hpp-x402-keychain generate
# → prints address — fund it with HPP gas, then add as Safe delegate

# Verify what's stored (address only, never the key):
npx -y -p @hpp-io/x402-mcp-bridge hpp-x402-keychain show

# Remove:
npx -y -p @hpp-io/x402-mcp-bridge hpp-x402-keychain delete

All commands accept an optional <account> positional (default delegate-default) so you can keep separate slots for sepolia / mainnet / project-specific delegates.

Architecture

See DESIGN.md in the parent task.

In short:

host (Claude Desktop)
   │ stdio (MCP)
   ▼
[ this bridge ]
   ─ Signer (delegate EOA)
   ─ AutoTopup (Safe + AllowanceModule)
   ─ remote MCP client (@x402/mcp wrapped)
   │
   │ SSE / StreamableHTTP (MCP + x402)
   ▼
remote x402 MCP server

Releasing to npm

Two paths, both via the GitHub Actions Publish workflow:

# (1) Recommended: tag-driven release
git checkout main && git pull
npm version patch          # or minor / major
git push --follow-tags     # → workflow runs, publishes to npm

# (2) Ad-hoc: workflow_dispatch from GitHub UI
#     Actions tab → "Publish to npm" → Run workflow
#     Optional `dry_run` toggle for verification

Required secret on the GitHub repo: NPM_TOKEN (npmjs.com → Profile → Access Tokens → Generate "Automation" token scoped to @hpp-io).

The prepublishOnly script in package.json runs typecheck && build locally too, so manual npm publish from a developer's machine still guards against shipping broken builds.

Related

This bridge is the MCP-host integration path (Claude Desktop, OpenClaw, Cursor, …). If you're building an agent / SDK integration instead — LangChain ReAct, OpenAI function-calling, Coinbase AgentKit, A2A seller↔buyer, etc. — see the runnable Gallery:

→ hpp-io/hpp-x402-agent-sample

Both paths share the same wallet/x402 layer; pick whichever surface fits your distribution.

Status

v0.0.1 — published on npm as @hpp-io/x402-mcp-bridge. Working end-to-end against HPP Sepolia (smoke proves both the "delegate has balance" and "delegate empty → autoTopup → pay" paths). Install with npx -y @hpp-io/x402-mcp-bridge or npm i -g @hpp-io/x402-mcp-bridge.

Roadmap:

• v0.1: package on npm, full README with screenshots, OS keychain wrapper for DELEGATE_PRIVATE_KEY (keychain://hpp-x402-delegate).
• v0.2: additional Signer implementations (HPP self-hosted server-wallet API, ERC-4337 session keys).
• v0.3: structured guardrail layer (allowlist of RESOURCE_SERVER_URL, per-call max payment cap) — mirrors Coinbase AgentKit's X402ActionProvider.

License

Apache-2.0