x402-MCP-Tool-Demo — eine echte 402, eine echte Ablehnung und eine echte Abrechnung

Eine minimale Demo des x402-Zahlungsprotokolls schützt einen MCP-artigen Tool-Endpoint, ausgeführt mit dem echten x402==2.16.0-Python-Paket und seinem standardmäßigen öffentlichen Facilitator (https://x402.org/facilitator) auf dem Base-Sepolia-Testnetz. Hier ist nichts handgeschriebenes Protokoll-JSON — jede Antwort in captured_responses/ stammt unverändert aus der Bibliothek.

Begleitend zu: So stellen Sie ein MCP-Tool in Rechnung: Ein funktionierender x402-Endpoint in unter einer Stunde.

Was es hier gibt

Related MCP server: 402-mcp

Ausführen

pip install -r requirements.txt
python gen_wallets.py          # writes wallets.json (gitignored) -- two fresh, empty keys
python server.py               # starts on 127.0.0.1:8402
python client_probe.py         # in a second terminal

Was Sie sehen werden

Runde 1 – keine Zahlung. Eine 402 mit einem payment-required-Header (Base64-JSON): Schema, Netzwerk, Asset-Vertrag, Betrag in der kleinsten Einheit des Tokens und die zu zahlende Adresse.

Runde 2 – eine echte signierte Zahlung, kein Guthaben. Der Client erstellt und signiert eine tatsächliche EIP-3009-Autorisierung mit dem Wegwerf-Schlüssel, hängt sie als X-PAYMENT an, und der Facilitator prüft sie gegen den echten Base-Sepolia-Chain-State. Die Antwort lautet:

{ "error": "invalid_exact_evm_insufficient_balance" }

Diese Zeichenfolge ist der echte Fehlercode des Facilitators, keine Vermutung — sie erhalten ihn, wenn das Protokoll genau wie vorgesehen funktioniert und der Zahlende schlicht kein Geld hat.

Runde 3 – finanziert und tatsächlich abgerechnet. Die agent_address wurde mit 20 Testnet-USDC aus dem öffentlichen Faucet von Circle finanziert, danach wurde client_probe.py erneut gegen denselben Server ausgeführt. Diesmal liefert Runde 2 eine 200:

{
  "url": "https://example.com/mcp",
  "recommendation": "expose as a priced x402 tool at $0.01/call",
  "paid": true
}

mit einem payment-response-Header, der sich wie folgt dekodieren lässt:

{ "success": true, "payer": "0x3214cB6C...E0E9", "transaction": "0x9530b663...0dd86", "network": "eip155:84532" }

Dieser Transaktions-Hash ist echt und unabhängig überprüfbar — auf Base Sepolia Blockscout ansehen: Status ok, an den USDC-Vertrag gesendet, Methode transferWithAuthorization — exakt das EIP-3009-Gasless-Transfer-Muster, das der Zahlende signiert hat. Jeder kann das überprüfen, ohne dieser README zu vertrauen.

Warum der manuelle Roundtrip in client_probe.py

x402 2.16.0 enthält PaymentRoundTripper, aber das ist ein Callback (handle_response(...)), der in einen eigenen httpx/requests-Transport eingebunden werden soll — es ist kein eigenständiger Transport zum direkten Einsetzen, trotz des Docstrings. client_probe.py ruft dieselben drei Primitiven, die es intern aufruft (get_payment_required_response → create_payment_payload → encode_payment_signature_header), direkt auf, was für eine Demo weniger bewegliche Teile bedeutet und identische Wire-Ausgabe erzeugt.

Sicherheitshinweise

• gen_wallets.py erzeugt Schlüssel mit eth_account.Account.create() — kryptografisch zufällig, nie finanziert, berührt in dieser Demo niemals das Mainnet.

• wallets.json ist in Git ignoriert. wallets.example.json zeigt die Struktur mit einer bekannten Burn-Adresse, sodass das Repo aus einem frischen Klon ohne Geheimnisse in der Git-Historie ausführbar ist.

• Die Facilitator-URL, das Netzwerk und der Asset-Vertrag sind die eigenen Testnet-Standardwerte der Bibliothek — hier spricht nichts mit dem Base-Mainnet oder bewegt echten Wert.