x402 Payment Protocol

The x402 protocol brings HTTP status code 402 (Payment Required) to life as a machine-readable payment protocol for APIs. The x402-mcp-validator validates MCP servers for x402 compliance — connecting to servers, discovering tools, probing for payment requirements, and validating payment options against the spec.

How x402 Works with MCP

When an MCP tool requires payment, the flow is:

Client calls a tool on the MCP server
Server responds with 402 including payment requirements (scheme, network, amount, asset, payTo)
Client processes payment through the specified payment network
Client retries the tool call with a payment receipt in the header
Server validates payment and executes the tool

This enables API monetization at the tool level — different tools can have different prices, and free tools can coexist with paid ones on the same server.

x402 MCP Validator

The validator connects to an MCP server end-to-end and returns a structured snapshot:

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()`

Connects to an MCP server, discovers capabilities, probes for x402 payment support, validates payment requirements, measures latency, and returns a structured snapshot.

Key	Type	Description	Required
`endpoint`	string	MCP server URL	Yes
`timeout`	number	Connection timeout in ms (default `10000`)	No

Returns: { status, messages, categories, entries }

`.compare()`

Compares two snapshots from .start() and returns a structured diff with added, removed, and modified items per section.

const before = await McpServerValidator.start( { endpoint: 'https://server.example.com/mcp' } )
// ... time passes, server changes ...
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	Type	Description	Required
`before`	object	Snapshot from a previous `.start()` call	Yes
`after`	object	Snapshot from a later `.start()` call	Yes

Returns: { status, messages, hasChanges, diff }

Flag	Description
`isReachable`	Server responded to HEAD request
`supportsMcp`	MCP handshake completed
`hasTools`	Server exposes at least one tool
`hasResources`	Server exposes at least one resource
`hasPrompts`	Server exposes at least one prompt
`supportsX402`	At least one tool returned a 402 payment error
`hasValidPaymentRequirements`	At least one payment option passed validation
`supportsExactScheme`	Has payment options with `scheme: 'exact'`
`supportsEvm`	Has payment options with `network: 'eip155:*'`
`supportsSolana`	Has payment options with `network: 'solana:*'`
`supportsTasks`	Server advertises tasks capability
`supportsMcpApps`	Server advertises mcpApps capability

Validation Pipeline

The validator processes an MCP server in six sequential steps:

Connect — Connects to the MCP server via StreamableHTTP with SSE fallback.
Discover — Discovers tools, resources, prompts, and capabilities through MCP protocol.
Classify — Classifies server capabilities into the 12 boolean categories.
Probe — Probes each tool for x402 payment requirements (HTTP 402 / JSON-RPC -32402).
Validate — Validates payment options: scheme, network, amount, asset, payTo, checksums.
Build Snapshot — Builds the structured snapshot with categories, entries, and validation messages.

Validation Codes

The validator uses structured error codes organized by category:

VAL -- Input Validation

Codes VAL-001 through VAL-015 cover input parameter validation for both .start() and .compare() methods. Examples: missing endpoint, invalid URL format, missing snapshots for comparison.

CON -- MCP Connection

Codes CON-001 through CON-011 cover server connectivity and MCP handshake issues. Examples: server not reachable, handshake failed, tools/list request failed.

PAY -- Payment Validation

Codes PAY-001 through PAY-102 cover x402 payment requirement validation in detail. Checks include: x402 version, resource format, accepts array, scheme, network prefix, amount format, asset address, payTo address with checksum validation, and timeout values.

PRB -- Probe

Codes PRB-004 and PRB-005 cover probe-level issues like unexpected exceptions and no tools available.

AUTH -- OAuth

Codes AUTH-002 through AUTH-011 cover OAuth discovery including metadata, PKCE support, protected resource metadata, client registration, and scope detection.

CMP -- Comparison

Codes CMP-001 through CMP-003 cover snapshot comparison integrity: different server endpoints, missing timestamps, and chronological ordering.