Guide + POC: x402 payment-gated MCP tools for AI agents

[andreabadesso]

Context

The primary use case for x402 is AI agents paying for tool calls. The viral adoption model described by the x402 community is:

1. Agent A discovers Agent B's MCP tools (via Bazaar or directory)
2. Agent A calls a tool → gets 402 Payment Required with price
3. Agent A auto-pays via x402 (escrow or channel on Hathor)
4. Agent B returns the result + its own MCP payment rail
5. Agent A installs B's payment rail → can forward it to other agents

This creates self-propagating adoption: one agent learns a paid MCP tool, and every connected agent can then discover and pay for it.

What we need

This is NOT something we implement as a core library — any developer can build x402-gated MCP servers using our existing tools. What we need is:

1. Guide: "How to build a paid MCP server with x402 on Hathor"

A step-by-step guide showing how to:

• Create an MCP server (using the MCP SDK)
• Gate tools with x402 (return 402 when a tool is called without payment)
• Accept payment via hathor-escrow or hathor-channel
• Return the payment rail in the tool response so agents can propagate it

The guide should reference:

• Our existing facilitator and resource server as the backend
• The @hathor/x402-client SDK (RFC 0002) as what the agent uses to auto-pay
• The @hathor/x402-server middleware (RFC 0003) as what the MCP server uses

2. Small POC: x402-gated MCP server

A minimal example MCP server with 1-2 paid tools. For example:

• get_weather tool — costs 1 HTR per call
• Returns 402 with Hathor escrow payment requirements
• Agent pays, tool executes, returns data

This would live in the x402-poc repo as an example (e.g., examples/mcp-server/).

3. Integration with Claude Code

Show how Claude Code (or any MCP-compatible AI assistant) can:

• Connect to the paid MCP server
• Automatically handle 402 → pay → retry using @hathor/x402-client
• Track spending across tool calls

How it connects to existing work

• The resource server (resource-server.js) is essentially a paid HTTP API — an MCP server is just the same thing exposed via MCP protocol instead of REST
• The facilitator handles verification and settlement — same for MCP tool calls
• The dApp shows the browser flow — the MCP guide shows the agent flow
• The client SDK (RFC 0002) wraps fetch() — it would also wrap MCP tool calls

References

• x402 MCP Server Guide
• Model Context Protocol
• x402 viral adoption thread
• RFC 0002: Client SDK