x402-Zahlungsprotokoll

Das x402-Protokoll erweckt den HTTP-Statuscode 402 (Payment Required) als maschinenlesbares Zahlungsprotokoll fuer APIs zum Leben. Der x402-mcp-validator validiert MCP-Server auf x402-Konformitaet — verbindet sich mit Servern, erkennt Tools, prueft auf Zahlungsanforderungen und validiert Zahlungsoptionen gegen die Spezifikation.

Wie x402 mit MCP funktioniert

Wenn ein MCP-Tool eine Zahlung erfordert, ist der Ablauf:

Client ruft ein Tool auf auf dem MCP-Server
Server antwortet mit 402 inklusive Zahlungsanforderungen (scheme, network, amount, asset, payTo)
Client verarbeitet die Zahlung ueber das angegebene Zahlungsnetzwerk
Client wiederholt den Tool-Aufruf mit einem Zahlungsbeleg im Header
Server validiert die Zahlung und fuehrt das Tool aus

Dies ermoeglicht API-Monetarisierung auf Tool-Ebene — verschiedene Tools koennen unterschiedliche Preise haben, und kostenlose Tools koennen neben kostenpflichtigen auf demselben Server existieren.

x402 MCP Validator

Der Validator verbindet sich End-to-End mit einem MCP-Server und gibt einen strukturierten Snapshot zurueck:

import { McpServerValidator } from 'x402-mcp-validator'

const { status, messages, categories, entries } = await McpServerValidator.start( {
    endpoint: 'https://your-mcp-server.example.com/mcp',
    timeout: 15000
} )

console.log( `Status: ${status ? 'PASS' : 'FAIL'}` )
console.log( `Tools: ${entries['tools'].length}` )
console.log( `x402: ${categories['supportsX402']}` )
console.log( `Networks: ${JSON.stringify( entries['x402']['networks'] )}` )

`.start()`

Verbindet sich mit einem MCP-Server, erkennt Capabilities, prueft auf x402-Zahlungsunterstuetzung, validiert Zahlungsanforderungen, misst Latenz und gibt einen strukturierten Snapshot zurueck.

Key	Typ	Beschreibung	Pflicht
`endpoint`	string	MCP-Server-URL	Ja
`timeout`	number	Verbindungs-Timeout in ms (Standard `10000`)	Nein

Gibt zurueck: { status, messages, categories, entries }

`.compare()`

Vergleicht zwei Snapshots von .start() und gibt einen strukturierten Diff mit hinzugefuegten, entfernten und geaenderten Elementen pro Abschnitt zurueck.

const before = await McpServerValidator.start( { endpoint: 'https://server.example.com/mcp' } )
// ... Zeit vergeht, Server aendert sich ...
const after = await McpServerValidator.start( { endpoint: 'https://server.example.com/mcp' } )

const { status, messages, hasChanges, diff } = McpServerValidator.compare( { before, after } )

console.log( `Changes detected: ${hasChanges}` )
console.log( `Tools added: ${diff['tools']['added'].length}` )
console.log( `Tools removed: ${diff['tools']['removed'].length}` )

Key	Typ	Beschreibung	Pflicht
`before`	object	Snapshot eines frueheren `.start()`-Aufrufs	Ja
`after`	object	Snapshot eines spaeteren `.start()`-Aufrufs	Ja

Gibt zurueck: { status, messages, hasChanges, diff }

Kategorien

Der Validator klassifiziert jeden Server mit 12 booleschen Flags:

Flag	Beschreibung
`isReachable`	Server hat auf HEAD-Anfrage geantwortet
`supportsMcp`	MCP-Handshake abgeschlossen
`hasTools`	Server stellt mindestens ein Tool bereit
`hasResources`	Server stellt mindestens eine Resource bereit
`hasPrompts`	Server stellt mindestens einen Prompt bereit
`supportsX402`	Mindestens ein Tool hat einen 402-Zahlungsfehler zurueckgegeben
`hasValidPaymentRequirements`	Mindestens eine Zahlungsoption hat die Validierung bestanden
`supportsExactScheme`	Hat Zahlungsoptionen mit `scheme: 'exact'`
`supportsEvm`	Hat Zahlungsoptionen mit `network: 'eip155:*'`
`supportsSolana`	Hat Zahlungsoptionen mit `network: 'solana:*'`
`supportsTasks`	Server bewirbt Tasks-Capability
`supportsMcpApps`	Server bewirbt mcpApps-Capability

Validierungs-Pipeline

Der Validator verarbeitet einen MCP-Server in sechs aufeinanderfolgenden Schritten:

Connect — Verbindet sich mit dem MCP-Server via StreamableHTTP mit SSE-Fallback.
Discover — Erkennt Tools, Resources, Prompts und Capabilities ueber das MCP-Protokoll.
Classify — Klassifiziert Server-Capabilities in die 12 booleschen Kategorien.
Probe — Prueft jedes Tool auf x402-Zahlungsanforderungen (HTTP 402 / JSON-RPC -32402).
Validate — Validiert Zahlungsoptionen: Scheme, Network, Amount, Asset, payTo, Checksummen.
Build Snapshot — Erstellt den strukturierten Snapshot mit Kategorien, Eintraegen und Validierungsmeldungen.

Validierungscodes

Der Validator verwendet strukturierte Fehlercodes, organisiert nach Kategorie:

VAL -- Eingabevalidierung

Codes VAL-001 bis VAL-015 decken die Eingabeparameter-Validierung fuer .start() und .compare() ab. Beispiele: fehlender Endpunkt, ungueltiges URL-Format, fehlende Snapshots fuer Vergleich.

CON -- MCP-Verbindung

Codes CON-001 bis CON-011 decken Server-Konnektivitaet und MCP-Handshake-Probleme ab. Beispiele: Server nicht erreichbar, Handshake fehlgeschlagen, tools/list-Anfrage fehlgeschlagen.

PAY -- Zahlungsvalidierung

Codes PAY-001 bis PAY-102 decken die x402-Zahlungsanforderungs-Validierung im Detail ab. Pruefungen umfassen: x402-Version, Resource-Format, Accepts-Array, Scheme, Netzwerk-Praefix, Betragsformat, Asset-Adresse, payTo-Adresse mit Checksummen-Validierung und Timeout-Werte.

PRB -- Probe

Codes PRB-004 und PRB-005 decken Probe-Level-Probleme ab wie unerwartete Ausnahmen und keine verfuegbaren Tools.

AUTH -- OAuth

Codes AUTH-002 bis AUTH-011 decken OAuth-Discovery ab einschliesslich Metadaten, PKCE-Unterstuetzung, Protected-Resource-Metadaten, Client-Registrierung und Scope-Erkennung.

CMP -- Vergleich

Codes CMP-001 bis CMP-003 decken die Snapshot-Vergleichs-Integritaet ab: unterschiedliche Server-Endpunkte, fehlende Zeitstempel und chronologische Reihenfolge.