basezap-mcp

An MCP (Model Context Protocol) server that exposes BaseZap's tipping-agent tools to any MCP client — Claude Desktop, Cursor, Claude Code, etc.

This server is read-only / non-custodial by design: it never holds private keys, never signs anything, and never broadcasts a transaction. It only fetches platform info, computes fee quotes, and builds unsigned ERC-20 transfer calldata for a separate wallet-connected client to sign and send.

Tools

• get_platform_info — chain, USDC address, platform fee (bps), fee wallet.
• get_tip_quote — given a USDC amount, returns the exact creator/platform fee split.
• build_tip_calldata — given a recipient address + amount, returns unsigned calldata for both legs of a tip. Never signs or sends anything.
• resolve_farcaster_username — resolves a Farcaster username to their verified wallet address (uses BaseZap's /api/resolve-user endpoint directly).

Install

npm install --ignore-scripts
npm run build

(--ignore-scripts avoids native-module build issues on some environments, e.g. Termux/Android — harmless to use anywhere.)

Running standalone (for testing)

npm start

Or test a single tool call directly over stdio without any MCP client:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_tip_quote","arguments":{"amountUsdc":1}}}' | node build/index.js

Claude Desktop config

Add this to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "basezap": {
      "command": "node",
      "args": ["/absolute/path/to/basezap-mcp/build/index.js"],
      "env": {
        "BASEZAP_USE_X402": "false"
      }
    }
  }
}

Replace the path with the real absolute path to build/index.js on your machine. Restart Claude Desktop after editing the config.

Free vs. paid (x402) mode

By default (BASEZAP_USE_X402=false or unset), the server calls BaseZap's free endpoint (/api/agent). Set BASEZAP_USE_X402=true to route calls through the paid x402 endpoint instead ($0.001 USDC per call).

Important: setting BASEZAP_USE_X402=true alone does NOT make the server pay automatically — you'll get a clear HTTP 402 Payment Required error on every call unless you've separately set up auto-pay (see below) or are using an MCP client/gateway that already handles x402 payment for you.

Optional: x402 auto-pay

See AUTOPAY.md for a from-scratch guide to making this server pay its own x402 fees automatically using a funded wallet. Read it carefully before using it — it involves putting a real private key in an environment variable, and a misconfigured auto-pay server can silently spend real money on every tool call. It is NOT wired in by default, and you should understand exactly what it does before enabling it.

Verified request contract

The exact request/response shape this server relies on was confirmed live against the real /api/agent endpoint (not assumed from documentation):

{ "tool": "get_tip_quote", "args": { "amount_usdc": 1 } }

returns:

{ "total_usdc": 1, "creator_receives_usdc": 0.95, "platform_fee_usdc": 0.05, "platform_fee_bps": 500 }

Note the API itself uses snake_case field names inside args — this server's MCP tool inputs use friendly camelCase (amountUsdc) and translate internally, so this is only relevant if you're modifying the server itself.