x402tools MCP Server

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

🛠 Tools

| Tool | Description | Price | |------|-------------|-------| | generate_qr | Generate QR code from text/URL | $0.001 | | generate_styled_qr | Artistic QR with shapes & gradients | $0.005 | | capture_screenshot | Website screenshot (dark mode, selectors) | $0.005 | | dns_lookup | DNS records (A, AAAA, MX, NS, TXT, SOA) | $0.002 | | parse_document | HTML/PDF → structured JSON | $0.001 | | screen_prompt_injection | Detect prompt injection / jailbreak | $0.003 | | validate_email | Email validation + deliverability + risk | $0.003 | | render_pdf | HTML/URL → PDF | $0.005 | | extract_text_ocr | Image → text via OCR | $0.005 |

🔌 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", "@x402tools/mcp-server"],
      "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: @x402tools/mcp-server
• GitHub: acrylicfiddle/x402-services

🚀 Self-host

git clone https://github.com/acrylicfiddle/x402-services
cd x402-services/services/mcp-server
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
cd services/mcp-server
mcp-publisher publish

📜 License

MIT