x402tools MCP Server

A Model Context Protocol server that gives AI agents 10 pay-per-call utility tools. Pay with USDC on Base via x402 protocol — agent's private key never leaves the agent.

🛠 Tools

🔌 Connect

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Hosted (HTTP):

{
  "mcpServers": {
    "x402tools": {
      "url": "https://mcp.x402tools.xyz/mcp"
    }
  }
}

Local (stdio with auto-pay convenience):

{
  "mcpServers": {
    "x402tools": {
      "command": "npx",
      "args": ["-y", "@x402-tools/mcp"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "x402tools": {
      "url": "https://mcp.x402tools.xyz/mcp"
    }
  }
}

Windsurf

Settings → MCP Servers → Add:

{
  "x402tools": {
    "serverUrl": "https://mcp.x402tools.xyz/mcp"
  }
}

Cline (VS Code)

.vscode/mcp.json:

{
  "mcpServers": {
    "x402tools": {
      "url": "https://mcp.x402tools.xyz/mcp"
    }
  }
}

Continue.dev

~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "streamable-http",
          "url": "https://mcp.x402tools.xyz/mcp"
        }
      }
    ]
  }
}

OpenAI Agents SDK / Responses API

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_label": "x402tools",
        "server_url": "https://mcp.x402tools.xyz/mcp",
        "require_approval": "never"
    }],
    input="Generate a QR code for https://x402tools.xyz"
)

Gemini / Google ADK

from google.genai import types

config = types.GenerateContentConfig(
    tools=[types.Tool(mcp_server={"url": "https://mcp.x402tools.xyz/mcp"})]
)

💸 Payment Model

This server uses payment passthrough — the MCP server holds NO wallet. Each agent provides their own signed payment per call.

Flow:

1. Agent calls a tool without payment → MCP returns 402 + payment requirements

2. Agent signs the payment locally with their wallet (hardware wallet, MPC, smart wallet, or private key)

3. Agent retries the tool with _payment argument or PAYMENT-SIGNATURE HTTP header

4. MCP forwards the signed payment to the underlying x402 service

Easiest signing: use @x402/fetch to wrap your fetch — it handles the 402 → sign → retry loop automatically:

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY);
const paidFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(account) }]
});

// Now calls to mcp.x402tools.xyz auto-pay on 402

Manual signing (for hardware wallets, MPC, smart accounts):

1. Read requirements.accepts[0] from the 402 response

2. Use @x402/evm's ExactEvmScheme.createPaymentPayload(2, requirements) with your ClientEvmSigner

3. Wrap as v2 PaymentPayload: { x402Version: 2, payload, extensions: {}, resource, accepted }

4. Base64-encode the JSON

5. Send as PAYMENT-SIGNATURE HTTP header (or _payment tool arg)

🏷 Protocol

• Network: Base mainnet (eip155:8453)

• Token: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

• Receiver: 0xcEbbB82a183Faa69b929eD1F417aAFc63fa3b5b6

• Header: PAYMENT-SIGNATURE (x402 v2)

🔍 Discovery Endpoints

• MCP server: https://mcp.x402tools.xyz/mcp

• Discovery JSON: https://mcp.x402tools.xyz/.well-known/mcp

• Health: https://mcp.x402tools.xyz/health

• MCP Registry: io.github.acrylicfiddle/x402tools

• npm: @x402-tools/mcp

• GitHub: acrylicfiddle/x402tools-mcp

🚀 Self-host

git clone https://github.com/acrylicfiddle/x402tools-mcp
cd x402tools-mcp
npm install
npm run build
PORT=4080 npm start
# MCP at http://localhost:4080/mcp

📦 Publishing to MCP Registry

brew install mcp-publisher
mcp-publisher login github
mcp-publisher publish

📜 License

MIT