Crate r402_mcp 

MCP (Model Context Protocol) integration for the x402 payment protocol.

This crate enables paid tool calls in MCP servers and automatic payment handling in MCP clients, following the x402 payment protocol specification.

Architecture

The crate provides framework-agnostic types and utilities that work with any MCP SDK implementation via serde_json::Value-based interfaces.

Client Usage

Wrap an MCP session with automatic x402 payment handling:

use r402_mcp::client::{X402McpClient, ClientOptions};

let mcp_client = X402McpClient::builder(my_mcp_caller)
    .scheme_client(evm_scheme_client)
    .build();

// Tool calls automatically handle 402 payment flows
let result = mcp_client.call_tool("get_weather", args).await?;

Server Usage

Wrap tool handlers with payment verification and settlement:

use r402_mcp::server::{PaymentWrapper, PaymentWrapperConfig};

let wrapper = PaymentWrapper::new(facilitator, PaymentWrapperConfig {
    accepts: payment_requirements,
    resource: Some(resource_info),
    ..Default::default()
});

// Process tool calls with automatic payment enforcement
let result = wrapper.process(request, |req| async { handle_tool(req).await }).await;

Utility Functions

The extract module provides low-level helpers for working with x402 payment data in MCP _meta fields:

• extract::extract_payment_from_meta - Extract payment payload from request meta
• extract::attach_payment_to_meta - Attach payment payload to request meta
• extract::extract_payment_response_from_meta - Extract settlement response from result meta
• extract::extract_payment_required_from_result - Extract 402 info from error results

Feature Flags

• rmcp — Built-in integration with the official rmcp Rust MCP SDK
• telemetry — Enables tracing instrumentation for debugging and monitoring

Modules

client

Client-side MCP x402 payment handling.

error

Error types for MCP x402 payment integration.

extract

Utility functions for extracting and attaching x402 payment data in MCP _meta fields.

server

Server-side MCP x402 payment wrapper.

types

Protocol types for MCP x402 payment integration.

Constants

PAYMENT_ERROR_KEY

MCP error envelope key for x402 payment errors (TS SDK compatibility).

PAYMENT_META_KEY

MCP _meta key for sending payment payloads (client → server).

PAYMENT_REQUIRED_CODE

JSON-RPC error code for payment required (x402).

PAYMENT_RESPONSE_META_KEY

MCP _meta key for settlement responses (server → client).