# x402tools MCP Server

[![npm](https://img.shields.io/npm/v/@x402-tools/mcp.svg)](https://www.npmjs.com/package/@x402-tools/mcp)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=x402tools)
[![smithery badge](https://smithery.ai/badge/kasatsiddhant/x402-tools)](https://smithery.ai/servers/kasatsiddhant/x402-tools)

A [Model Context Protocol](https://modelcontextprotocol.io) 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

| Tool | Description | Price |
|------|-------------|-------|
| `qr.generate` | Generate QR code from text/URL | $0.01 |
| `qr.generate_styled` | Artistic QR with shapes & gradients | $0.05 |
| `image.screenshot` | Website screenshot (dark mode, selectors) | $0.05 |
| `dns.lookup` | DNS records (A, AAAA, MX, NS, TXT, SOA) | $0.02 |
| `document.parse` | HTML/PDF → structured JSON | $0.01 |
| `security.screen` | Detect prompt injection / jailbreak | $0.03 |
| `email.validate` | Email validation + deliverability + risk | $0.03 |
| `document.render_pdf` | HTML/URL → PDF | $0.05 |
| `image.ocr` | Image → text via OCR | $0.05 |
| `prospect.enrich` | Name + domain → sales-ready buyer profile + cold-email opener | $0.50 |

## 🔌 Connect

### Claude Desktop

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

**Hosted (HTTP):**
```json
{
  "mcpServers": {
    "x402tools": {
      "url": "https://mcp.x402tools.xyz/mcp"
    }
  }
}
```

**Local (stdio with auto-pay convenience):**
```json
{
  "mcpServers": {
    "x402tools": {
      "command": "npx",
      "args": ["-y", "@x402-tools/mcp"],
      "env": {
        "WALLET_PRIVATE_KEY": "0x..."
      }
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "x402tools": {
      "url": "https://mcp.x402tools.xyz/mcp"
    }
  }
}
```

### Windsurf

Settings → MCP Servers → Add:
```json
{
  "x402tools": {
    "serverUrl": "https://mcp.x402tools.xyz/mcp"
  }
}
```

### Cline (VS Code)

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

### Continue.dev

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

### OpenAI Agents SDK / Responses API

```python
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

```python
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:

```typescript
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`](https://registry.modelcontextprotocol.io/v0/servers?search=x402tools)
- **npm**: [`@x402-tools/mcp`](https://www.npmjs.com/package/@x402-tools/mcp)
- **GitHub**: [acrylicfiddle/x402tools-mcp](https://github.com/acrylicfiddle/x402tools-mcp)

## 🚀 Self-host

```bash
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

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

## 📜 License

MIT