x402-mcp-server

# x402 MCP Server An **MCP (Model Context Protocol) server** that gives Claude agents the ability to pay for web resources using **USDC on Solana** via the [x402 protocol](https://x402.org). Built for the **Solana x402 Hackathon** — MCP Servers track. --- ## What it does The x402 protocol extends HTTP with a **402 Payment Required** flow: ``` Agent → GET /paid-endpoint ← 402 + payment details (amount, recipient, memo) Agent → pays USDC on Solana Agent → GET /paid-endpoint + X-Payment: x402 <proof> ← 200 + content ``` This MCP server handles the entire flow autonomously. Claude just calls `pay_and_fetch("https://...")` and the server handles the payment, confirmation, and retry. --- ## Tools | Tool | Description | |---|---| | `pay_and_fetch` | Fetch a URL, pay via USDC if 402 required. Enforces a `max_usdc` safety limit. | | `check_balance` | Check USDC + SOL balance of the configured wallet | | `get_payment_info` | Probe a URL for payment requirements without paying | | `list_transactions` | List all payments made this session | | `configure_wallet` | Set the active Solana wallet (RPC, private key, network) | --- ## Quickstart ```bash git clone https://github.com/dockfixlabs/x402-mcp-server cd x402-mcp-server pip install httpx # optional — core uses urllib only ``` ### Add to Claude Code (`~/.claude/claude_code_config.json`) ```json { "mcpServers": { "x402": { "command": "python3", "args": ["/path/to/x402-mcp-server/src/mcp_server.py"], "env": { "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com", "SOLANA_PRIVATE_KEY": "your-base58-private-key", "X402_MAX_USDC": "0.10" } } } } ``` ### Test with the demo server ```bash # Terminal 1: start x402-protected API python3 src/demo_server.py # Terminal 2: Claude Code with MCP connected # Then in Claude: # > pay_and_fetch("http://localhost:8402/paid/data", max_usdc=0.01) ``` --- ## Environment variables | Variable | Default | Description | |---|---|---| | `SOLANA_RPC_URL` | mainnet-beta | Solana RPC endpoint | | `SOLANA_PRIVATE_KEY` | — | Base58 private key (required for payments) | | `X402_MAX_USDC` | `0.10` | Global max spend per request | --- ## Architecture ``` x402-mcp-server/ ├── src/ │ ├── mcp_server.py MCP stdio server — 5 tools │ ├── x402_client.py x402 payment flow + Solana USDC client │ └── demo_server.py x402-protected API (for local testing) ├── tests/ │ └── test_x402.py 21 unit tests (all passing) ├── .github/workflows/ci.yml └── README.md ``` --- ## Security - **`max_usdc` hard limit** — server refuses to pay more than the configured ceiling per request - **Payment caching** — reuses proofs for the same URL within a session - **No key storage** — private key passed via environment variable only - **Confirmation check** — waits for on-chain confirmation before retrying request --- ## Solana x402 Hackathon Built for the **MCP Servers** track. Demonstrates: - Full x402 protocol implementation (402 → payment → retry) - MCP server with 5 tools for agent-native payment flows - Pure stdlib Python core (no external deps required for basic operation) - 21 unit tests with mocked Solana/HTTP calls - Demo server for end-to-end local testing **Author:** [dockfixlabs](https://github.com/dockfixlabs)