@qbtlabs/x402-mcp

Payment wrapper for MCP servers using x402 protocol. Monetize your MCP tools with stablecoin micropayments.

Installation

npm install @qbtlabs/x402-mcp

Quick Start

Option 1: Proxy Mode (Zero Code Changes)

Wrap any existing MCP server with payment gating:

npx @qbtlabs/x402-mcp-proxy \
  --upstream "npx your-mcp-server" \
  --recipient 0xYourWalletAddress \
  --price 0.01

Options:

• -u, --upstream — MCP server command to proxy (required)
• -r, --recipient — Wallet address to receive payments (required)
• -p, --price — Default price per call in USD or tier (default: 0.001)
• -f, --free — Tool name to make free (repeatable)
• --testnet — Use testnet (Base Sepolia)

Option 2: SDK Integration

For more control, wrap individual tools:

import { wrapTool, createPaidServer } from '@qbtlabs/x402-mcp';

// Define a tool with pricing
const weatherTool = wrapTool({
  name: 'get_weather',
  description: 'Get current weather for a location',
  inputSchema: {
    type: 'object',
    properties: {
      location: { type: 'string', description: 'City name' }
    },
    required: ['location']
  },
  handler: async ({ location }) => {
    const weather = await fetchWeather(location);
    return { temperature: weather.temp, conditions: weather.conditions };
  }
}, { 
  price: 0.001  // $0.001 per call
});

// Create paid server
const { run } = createPaidServer({
  name: 'weather-server',
  evmRecipient: '0xYourWalletAddress',
  tools: [weatherTool],
});

// Start server
await run();

Pricing Tiers

Tier	Price	Use Case
'free'	$0.00	Discovery, listing
'read'	$0.001	Data queries
'analysis'	$0.005	Computed insights
'write'	$0.01	Mutations
number	Custom	Any USD amount

Dynamic Pricing

Charge based on input complexity:

const paidTool = wrapTool(myTool, {
  price: (input) => {
    const tokens = countTokens(input.text);
    return tokens * 0.0001; // $0.0001 per token
  }
});

Free Quota

Let agents try before they buy:

const paidTool = wrapTool(myTool, {
  price: 0.01,
  freeQuota: 10,  // First 10 calls free per agent
});

Multi-Chain Support

Accept payments on Base, Solana, or Cardano:

const { run } = createPaidServer({
  name: 'my-server',
  evmRecipient: '0xYourBaseAddress',
  solanaRecipient: 'YourSolanaPubkey',
  cardanoRecipient: 'addr1q...',
  testnet: process.env.NODE_ENV !== 'production',
  tools: [/* ... */],
});

Client Configuration

Agents need to sign payments. For Claude Desktop:

{
  "mcpServers": {
    "your-server": {
      "command": "npx",
      "args": ["@qbtlabs/x402-mcp-proxy", "--upstream", "your-server", "--recipient", "0x..."],
      "env": {
        "X402_PRIVATE_KEY": "0xAgentPrivateKey"
      }
    }
  }
}

API Reference

wrapTool(tool, pricing)

Wrap a tool definition with pricing.

interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: object;
  handler: (input: unknown) => Promise<unknown>;
}

interface ToolPricing {
  price: PricingTier | ((input: unknown) => number);
  recipient?: string;  // Override recipient for this tool
  freeQuota?: number;  // Free calls per agent
}

createPaidServer(options)

Create an MCP server with payment gating.

interface PaidServerOptions {
  name: string;
  version?: string;
  tools: PricedTool[];
  evmRecipient?: string;
  solanaRecipient?: string;
  cardanoRecipient?: string;
  testnet?: boolean;
  defaultPrice?: PricingTier;
}

PaymentMiddleware

Low-level middleware for custom integrations.

const middleware = new PaymentMiddleware({
  evmRecipient: '0x...',
});

middleware.registerTool(paidTool);

const check = middleware.checkPayment('tool_name', input, agentAddress);
if (check.required && !hasPaid) {
  const reqs = middleware.getPaymentRequirements('tool_name', check.amount);
  // Return 402 with reqs
}

Related

• @qbtlabs/x402 — Core x402 protocol
• docs.qbtlabs.io — Full documentation

License

MIT © QBT Labs