# basezap-mcp

An MCP (Model Context Protocol) server that exposes [BaseZap](https://basefarcaster.vercel.app)'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

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

```bash
npm start
```

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

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

```json
{
  "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):

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

returns:

```json
{ "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.