Skip to main content
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:
  1. Client calls a tool on the MCP server
  2. Server responds with 402 including payment requirements (scheme, network, amount, asset, payTo)
  3. Client processes payment through the specified payment network
  4. Client retries the tool call with a payment receipt in the header
  5. 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.
KeyTypeDescriptionRequired
endpointstringMCP server URLYes
timeoutnumberConnection 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}` )
KeyTypeDescriptionRequired
beforeobjectSnapshot from a previous .start() callYes
afterobjectSnapshot from a later .start() callYes
Returns: { status, messages, hasChanges, diff }

​
Categories

The validator classifies each server with 12 boolean flags:
FlagDescription
isReachableServer responded to HEAD request
supportsMcpMCP handshake completed
hasToolsServer exposes at least one tool
hasResourcesServer exposes at least one resource
hasPromptsServer exposes at least one prompt
supportsX402At least one tool returned a 402 payment error
hasValidPaymentRequirementsAt least one payment option passed validation
supportsExactSchemeHas payment options with scheme: 'exact'
supportsEvmHas payment options with network: 'eip155:*'
supportsSolanaHas payment options with network: 'solana:*'
supportsTasksServer advertises tasks capability
supportsMcpAppsServer advertises mcpApps capability

​
Validation Pipeline

The validator processes an MCP server in six sequential steps:
1

Connect

Connects to the MCP server via StreamableHTTP with SSE fallback.
2

Discover

Discovers tools, resources, prompts, and capabilities through MCP protocol.
3

Classify

Classifies server capabilities into the 12 boolean categories.
4

Probe

Probes each tool for x402 payment requirements (HTTP 402 / JSON-RPC -32402).
5

Validate

Validates payment options: scheme, network, amount, asset, payTo, checksums.
6

Build Snapshot

Builds the structured snapshot with categories, entries, and validation messages.

​
Validation Codes

The validator uses structured error codes organized by category:
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.
Codes CON-001 through CON-011 cover server connectivity and MCP handshake issues. Examples: server not reachable, handshake failed, tools/list request failed.
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.
Codes PRB-004 and PRB-005 cover probe-level issues like unexpected exceptions and no tools available.
Codes AUTH-002 through AUTH-011 cover OAuth discovery including metadata, PKCE support, protected resource metadata, client registration, and scope detection.
Codes CMP-001 through CMP-003 cover snapshot comparison integrity: different server endpoints, missing timestamps, and chronological ordering.
Each validation message includes an error code, severity (ERROR, WARNING, INFO), and a human-readable description. Use the codes to programmatically identify and handle specific issues.