MCP Server with x402

What is this integration?

This guide walks you through running an MCP server that can access paid APIs using the x402 protocol. The MCP server acts as a bridge between Claude Desktop (or any MCP-compatible client) and a paid API (such as the sample weather API in the x402 repo). When Claude (or another agent) calls a tool, the MCP server will:

Detect if the API requires payment (via HTTP 402 with PAYMENT-REQUIRED header)
Automatically handle the payment using your wallet via the registered x402 scheme
Return the paid data to the client (e.g., Claude)

This lets you (or your agent) access paid APIs programmatically, with no manual payment steps.

Prerequisites

Node.js v20+ (install via nvm)
pnpm v10 (install via pnpm.io/installation)
An x402-compatible server to connect to (for this demo, we’ll use the sample express server with weather data from the x402 repo, or any external x402 API)
An Ethereum wallet with USDC (on Base Sepolia or Base Mainnet) and/or a Solana wallet with USDC (on Devnet or Mainnet)
Claude Desktop with MCP support

Quick Start

1. Install and Build

# Clone the x402 repository
git clone https://github.com/x402-foundation/x402.git
cd x402/examples/typescript

# Install dependencies and build packages
pnpm install && pnpm build

# Navigate to the MCP client example
cd clients/mcp

2. Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration:

{
  "mcpServers": {
    "demo": {
      "command": "pnpm",
      "args": [
        "--silent",
        "-C",
        "<absolute path to this repo>/examples/typescript/clients/mcp",
        "dev"
      ],
      "env": {
        "EVM_PRIVATE_KEY": "<private key of a wallet with USDC on Base Sepolia>",
        "SVM_PRIVATE_KEY": "<base58-encoded private key of a Solana wallet with USDC on Devnet>",
        "RESOURCE_SERVER_URL": "http://localhost:4021",
        "ENDPOINT_PATH": "/weather"
      }
    }
  }
}

3. Start the x402 Server

Make sure your x402-compatible server is running at the URL specified in RESOURCE_SERVER_URL:

# In another terminal, from the examples/typescript directory
cd servers/express
pnpm dev

4. Restart Claude Desktop

Restart Claude Desktop to load the new MCP server, then ask Claude to use the get-data-from-resource-server tool.

Environment Variables

Variable	Description	Required
`EVM_PRIVATE_KEY`	Your EVM wallet’s private key (0x prefixed)	One of EVM or SVM required
`SVM_PRIVATE_KEY`	Your Solana wallet’s private key (base58 encoded)	One of EVM or SVM required
`RESOURCE_SERVER_URL`	The base URL of the paid API	Yes
`ENDPOINT_PATH`	The specific endpoint path (e.g., `/weather`)	Yes

Implementation

The MCP server uses @x402/axios to wrap axios with automatic payment handling:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import axios from "axios";
import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { BatchSettlementEvmScheme } from "@x402/evm/batch-settlement/client";
import { toClientEvmSigner } from "@x402/evm";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";
import { config } from "dotenv";

config();

const evmPrivateKey = process.env.EVM_PRIVATE_KEY as `0x${string}`;
const svmPrivateKey = process.env.SVM_PRIVATE_KEY as string;
const baseURL = process.env.RESOURCE_SERVER_URL || "http://localhost:4021";
const endpointPath = process.env.ENDPOINT_PATH || "/weather";

if (!evmPrivateKey && !svmPrivateKey) {
  throw new Error("At least one of EVM_PRIVATE_KEY or SVM_PRIVATE_KEY must be provided");
}

/**
 * Creates an axios client configured with x402 payment support for EVM and/or SVM.
 */
async function createClient() {
  const client = new x402Client();

  // Register EVM scheme if private key is provided
  if (evmPrivateKey) {
    const account = privateKeyToAccount(evmPrivateKey);
    client.register("eip155:*", new ExactEvmScheme(account));
    const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
    const batchSigner = toClientEvmSigner(account, publicClient);
    client.register(
      "eip155:*",
      new BatchSettlementEvmScheme(batchSigner, {
        depositPolicy: { depositMultiplier: 5 },
      }),
    );
  }

  // Register SVM scheme if private key is provided
  if (svmPrivateKey) {
    const svmSigner = await createKeyPairSignerFromBytes(base58.decode(svmPrivateKey));
    client.register("solana:*", new ExactSvmScheme(svmSigner));
  }

  return wrapAxiosWithPayment(axios.create({ baseURL }), client);
}

async function main() {
  const api = await createClient();

  // Create an MCP server
  const server = new McpServer({
    name: "x402 MCP Client Demo",
    version: "2.0.0",
  });

  // Add a tool that calls the paid API
  server.tool(
    "get-data-from-resource-server",
    "Get data from the resource server (in this example, the weather)",
    {},
    async () => {
      const res = await api.get(endpointPath);
      return {
        content: [{ type: "text", text: JSON.stringify(res.data) }],
      };
    },
  );

  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

How It Works

The MCP server exposes a tool that, when called, fetches data from a paid API endpoint. If the endpoint requires payment, the x402 axios wrapper automatically handles the payment handshake:

402 Response: The server returns HTTP 402 with PAYMENT-REQUIRED header
Parse Requirements: The wrapper extracts payment requirements from the header
Create Payment: Uses the registered scheme (EVM or SVM) to create a payment payload
Retry Request: Sends the original request with the PAYMENT-SIGNATURE header
Return Data: Once payment is verified, the data is returned to Claude

Policy Checks Before Payment

This example auto-approves payments for local testing. In production, the MCP bridge should check the payment requirements before creating or signing a payment payload. The client hooks are the right place to enforce those rules. At minimum, compare the selected requirement against your expected tool call:

maximum amount and currency
expected network and scheme
expected resource server or facilitator
tool name and user-requested operation
per-user, per-agent, or per-session spend limits

Using spend policies (recommended)

Pass policies directly to createx402MCPClient to filter payment requirements before any payment is created. Policies run after built-in spendControls and before the wallet signs. By default the underlying x402Client only allows recognized default assets and applies a $1 USD spend cap unless you override spendControls (raise/disable maxAmountPerPayment, opt into other tokens via allowedAssets, or set spendControls: false):

import { createx402MCPClient } from "@x402/mcp";
import { ExactEvmScheme } from "@x402/evm/exact/client";

const client = createx402MCPClient({
  name: "my-agent",
  version: "1.0.0",
  schemes: [
    { network: "eip155:84532", client: new ExactEvmScheme(account) },
  ],
  // Reject any payment requirement above 1 USDC (6 decimals)
  policies: [
    (_version, reqs) => reqs.filter(r => BigInt(r.amount ?? "0") < 1_000_000n),
  ],
  // Optionally override which accept entry is selected (default: server-ordered accepts[0])
  paymentRequirementsSelector: (reqs) => reqs.find(r => r.network === "eip155:84532"),
});

Capping tool-call timeouts

By default, the x402 MCP client caps derived tool-call timeouts at 10 minutes (600 seconds). The cap applies to both the initial probe call and the paid retry. You can lower or raise this limit using maxRequestTimeoutSeconds (TypeScript/Python) or MaxRequestTimeout (Go):

TypeScript
Python
Go

import { createx402MCPClient } from "@x402/mcp";

const client = createx402MCPClient({
  name: "my-agent",
  version: "1.0.0",
  schemes: [{ network: "eip155:84532", client: new ExactEvmScheme(account) }],
  // Cap tool-call timeouts at 2 minutes (default: 600s)
  maxRequestTimeoutSeconds: 120,
});

Per-call overrides are also supported via callTool’s options.timeout (milliseconds), which takes precedence over the cap.

from x402.mcp import wrap_mcp_client_with_payment

x402_mcp = wrap_mcp_client_with_payment(
    mcp_client,
    payment_client,
    max_request_timeout_seconds=120,  # default: 600
)

Pass read_timeout_seconds to individual call_tool calls to override the cap for a single request.

import (
    "time"
    x402mcp "github.com/x402-foundation/x402/go/v2/mcp"
)

client := x402mcp.NewX402MCPClient(session, paymentClient, x402mcp.Options{
    MaxRequestTimeout: 2 * time.Minute, // default: 10 minutes
})

The timeout is derived from the payment requirement’s maxTimeoutSeconds field, capped by maxRequestTimeoutSeconds. If the accept’s maxTimeoutSeconds exceeds the cap, the cap wins.

Using the onPaymentRequested hook

For per-call logic (e.g. checking tool name or prompting the user), use onPaymentRequested:

const x402Mcp = new x402MCPClient(mcpClient, paymentClient, {
  onPaymentRequested: async ({ toolName, paymentRequired }) => {
    const requirement = paymentRequired.accepts[0];

    if (toolName !== "get_weather") return false;
    if (requirement.network !== "eip155:84532") return false;
    if (BigInt(requirement.amount) > 1_000n) return false;

    return true;
  },
});

If a payment requirement does not match the intended tool call, deny it before the wallet signs. Avoid relying only on model prompts for spend controls; keep the policy check in code near the payment client.

Multi-Network Support

The example supports both EVM (Base, Ethereum) and Solana networks. The x402 client automatically selects the appropriate scheme based on the payment requirements:

import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { ExactSvmScheme } from "@x402/svm/exact/client";
import { BatchSettlementEvmScheme } from "@x402/evm/batch-settlement/client";
import { toClientEvmSigner } from "@x402/evm";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();

const account = privateKeyToAccount(evmPrivateKey);
const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });

// Register EVM schemes for Base/Ethereum payments (exact + batch-settlement)
client.register("eip155:*", new ExactEvmScheme(account));
client.register(
  "eip155:*",
  new BatchSettlementEvmScheme(toClientEvmSigner(account, publicClient), {
    depositPolicy: { depositMultiplier: 5 },
  }),
);

// Register SVM scheme for Solana payments
client.register("solana:*", new ExactSvmScheme(svmSigner));

// Now handles both EVM and Solana networks automatically
const httpClient = wrapAxiosWithPayment(axios.create({ baseURL }), client);

When the server returns a 402 response, the client checks the network field in the payment requirements:

eip155:* networks use the registered EVM schemes (exact, upto, batch-settlement, etc.)
solana:* networks use the SVM scheme

Batch settlement: Paid APIs that advertise scheme: "batch-settlement" require BatchSettlementEvmScheme on eip155:* (in addition to ExactEvmScheme). The Implementation section and the snippet above register both so tools work against exact servers and batch-settlement APIs. See Batch settlement.

Response Handling

Payment Required (402)

When a payment is required, the client receives:

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64-encoded JSON>

The wrapper automatically:

Parses the payment requirements
Creates and signs a payment using the appropriate scheme
Retries the request with the PAYMENT-SIGNATURE header

Successful Response

After payment is processed, the MCP server returns:

{
  "content": [
    {
      "type": "text",
      "text": "{\"report\":{\"weather\":\"sunny\",\"temperature\":70}}"
    }
  ]
}

Architecture Diagram

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop │────▶│   MCP Server    │────▶│  x402 API       │
│                 │     │  (x402 client)  │     │  (paid endpoint)│
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │  1. Call tool         │  2. GET /weather      │
        │                       │                       │
        │                       │  3. 402 + requirements│
        │                       │◀──────────────────────│
        │                       │                       │
        │                       │  4. Sign payment      │
        │                       │                       │
        │                       │  5. Retry with payment│
        │                       │──────────────────────▶│
        │                       │                       │
        │                       │  6. 200 + data        │
        │                       │◀──────────────────────│
        │                       │                       │
        │  7. Return response   │                       │
        │◀──────────────────────│                       │

Dependencies

The example uses these x402 v2 packages:

{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.9.0",
    "@x402/axios": "workspace:*",
    "@x402/evm": "workspace:*",
    "@x402/svm": "workspace:*",
    "axios": "^1.13.2",
    "viem": "^2.39.0",
    "@solana/kit": "^2.1.1",
    "@scure/base": "^1.2.6"
  }
}

How the Pieces Fit Together

x402-compatible server: Hosts the paid API (e.g., weather data). Responds with HTTP 402 and PAYMENT-REQUIRED header if payment is required.
MCP server (this implementation): Acts as a bridge, handling payment via @x402/axios and exposing tools to MCP clients.
Claude Desktop: Calls the MCP tool, receives the paid data, and displays it to the user.

Making Your MCP Tools Discoverable via Bazaar

If you are building an MCP server (not just a client bridge), you can make your paid tools visible in the x402 Bazaar so AI agents and other buyers can discover them without prior knowledge of your server. Pass extensions in the payment wrapper config with the Bazaar discovery metadata:

import { createPaymentWrapper } from "@x402/mcp";
import { declareDiscoveryExtension } from "@x402/extensions/bazaar";

const paid = createPaymentWrapper(resourceServer, {
  accepts,
  resource: {
    url: "mcp://tool/get_weather",
    description: "Get current weather for a city",
  },
  // Bazaar discovery metadata — facilitators will catalog this tool
  extensions: declareDiscoveryExtension({
    toolName: "get_weather",
    description: "Get current weather for a city",
    transport: "sse",
    inputSchema: {
      properties: { city: { type: "string", description: "City name" } },
      required: ["city"],
    },
    example: { city: "San Francisco" },
  }),
});

When a client pays for the tool, the facilitator extracts the Bazaar extension from the payment payload and indexes the tool in /discovery/resources with type: "mcp". Buyers can then discover it by querying a Bazaar-enabled facilitator:

const mcpTools = await client.extensions.bazaar.listResources({ type: "mcp" });

See the full Bazaar documentation for details on buyers querying and calling discovered MCP tools.

Next Steps

See the full example in the repo
Try integrating with your own x402-compatible APIs
Extend the MCP server with more tools or custom logic as needed
Learn about building x402 servers
Explore the Bazaar discovery layer

Welcome

Getting Started

Core Concepts

Payment Schemes

Extensions

Advanced Concepts

Guides

Developer Tools

SDK Features

MCP Server with x402

What is this integration?

Prerequisites

Quick Start

1. Install and Build

2. Configure Claude Desktop

3. Start the x402 Server

4. Restart Claude Desktop

Environment Variables

Implementation

How It Works

Policy Checks Before Payment

Using spend policies (recommended)

Capping tool-call timeouts

Using the onPaymentRequested hook

Multi-Network Support

Response Handling

Payment Required (402)

Successful Response

Architecture Diagram

Dependencies

How the Pieces Fit Together

Making Your MCP Tools Discoverable via Bazaar

Next Steps

​What is this integration?

​Prerequisites

​Quick Start

​1. Install and Build

​2. Configure Claude Desktop

​3. Start the x402 Server

​4. Restart Claude Desktop

​Environment Variables

​Implementation

​How It Works

​Policy Checks Before Payment

​Using spend policies (recommended)

​Capping tool-call timeouts

​Using the onPaymentRequested hook

​Multi-Network Support

​Response Handling

​Payment Required (402)

​Successful Response

​Architecture Diagram

​Dependencies

​How the Pieces Fit Together

​Making Your MCP Tools Discoverable via Bazaar

​Next Steps

What is this integration?

Prerequisites

Quick Start

1. Install and Build

2. Configure Claude Desktop

3. Start the x402 Server

4. Restart Claude Desktop

Environment Variables

Implementation

How It Works

Policy Checks Before Payment

Using spend policies (recommended)

Capping tool-call timeouts

Using the onPaymentRequested hook

Multi-Network Support

Response Handling

Payment Required (402)

Successful Response

Architecture Diagram

Dependencies

How the Pieces Fit Together

Making Your MCP Tools Discoverable via Bazaar

Next Steps