@acrylicfiddle/x402tools-mcp

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:

• Agent calls a tool without payment → MCP returns 402 + payment requirements
• Agent signs the payment locally with their wallet (hardware wallet, MPC, smart wallet, or private key)
• Agent retries the tool with _payment argument or PAYMENT-SIGNATURE HTTP header
• 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):

• Read requirements.accepts[0] from the 402 response
• Use @x402/evm's ExactEvmScheme.createPaymentPayload(2, requirements) with your ClientEvmSigner
• Wrap as v2 PaymentPayload: { x402Version: 2, payload, extensions: {}, resource, accepted }
• Base64-encode the JSON
• 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