HPP x402 MCP Bridge

What HPP x402 MCP Bridge does

HPP x402 MCP Bridge gives MCP hosts access to HPP's x402 payment flow. Agents can search the curated HPP service directory, inspect a service's input schema and example, then invoke the service while paying from an agent wallet. Payment is made in HPP USDC.e, and each paid call is constrained by the configured spending cap.

The bridge supports calls to discovered HTTP, MCP, and A2A services. It also includes a tool for calling arbitrary x402 HTTP endpoints and another for paying and messaging an A2A agent. Read-only discovery does not handle funds or expose wallet keys.

How it works

An MCP host starts the bridge as a child process over stdio. A minimal host configuration can run the package through npx:

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

The bridge can create a wallet key in the operating system keychain when no private key is supplied. Agents can report the wallet address, search the HPP directory, inspect service requirements, and submit paid calls. The separate hpp-x402 command-line interface provides equivalent terminal workflows through commands such as discover, describe, and call.

Payment can instead use an HPP Smart Wallet delegation. The delegation is issued to the agent's address and limited by the wallet owner, including an expiration and spending limit. The bridge validates the delegation against the agent key and selected network when installed and when it starts.

Setup and configuration

Install with the project installer for macOS or Linux, the PowerShell installer for Windows, or npm:

npm install -g @hpp-io/x402-mcp-bridge

Node.js 20 or newer is required. Run hpp-x402 setup --install <host> to create a wallet and register the bridge with a supported host, then use hpp-x402 fund to obtain the wallet funding destination and hpp-x402 status to verify the setup. A headless machine without an operating-system keychain can use setup --print-key.

The default network is HPP Sepolia. HPP_NETWORK selects between HPP Sepolia and HPP Mainnet. DELEGATE_PRIVATE_KEY supplies the agent key; if omitted, the bridge can create and store one in the OS keychain. HPP_PAYMENT_DELEGATION enables delegated payment from a user's smart account. RESOURCE_SERVER_URL can proxy one upstream MCP server, while SAFE_ADDRESS and ALLOWANCE_MODULE_ADDRESS together enable Safe governance mode.

Tools and capabilities

• wallet_address reports the wallet address used for funding or delegation.
• hpp_discover searches the curated HPP directory without making payments.
• hpp_describe returns a service's input arguments, schema, and example.
• hpp_call pays for and invokes a discovered HTTP, MCP, or A2A service.
• x402_http_call pays for and invokes any x402 HTTP endpoint.
• pay_a2a_agent pays and sends a message to another A2A agent.

Limitations and notes

The bridge is intended for HPP x402 payments and defaults to HPP Sepolia. Mainnet use requires selecting the Mainnet network. A bare package invocation starts the MCP server; CLI commands require invoking the hpp-x402 executable separately.

Delegation values are checked against the agent key and network, and revoked, expired, or cross-network delegations prevent the bridge from starting. Delegation values written through installation may remain in shell history, so they should be handled like capped payment credentials. Discovery is limited to the curated HPP directory, while arbitrary endpoint access is available through the dedicated x402 HTTP tool.