basezap-mcp

Un servidor MCP (Protocolo de Contexto de Modelo) que expone las herramientas del agente de propinas de BaseZap a cualquier cliente MCP — Claude Desktop, Cursor, Claude Code, etc.

Este servidor es de solo lectura / no custodio por diseño: nunca retiene claves privadas, nunca firma nada y nunca transmite una transacción. Solo obtiene información de la plataforma, calcula cotizaciones de tarifas y construye datos de llamada sin firmar para transferencias ERC-20 que un cliente separado conectado a una billetera debe firmar y enviar.

Herramientas

• get_platform_info — cadena, dirección de USDC, tarifa de plataforma (pbs), billetera de tarifas.

• get_tip_quote — dado un monto en USDC, devuelve la división exacta de la tarifa del creador/plataforma.

• build_tip_calldata — dada una dirección de destinatario + monto, devuelve datos de llamada sin firmar para ambas partes de una propina. Nunca firma ni envía nada.

• resolve_farcaster_username — resuelve un nombre de usuario de Farcaster a su dirección de billetera verificada (usa directamente el endpoint /api/resolve-user de BaseZap).

Related MCP server: x402-bazaar-mcp

Instalar

npm install --ignore-scripts
npm run build

(--ignore-scripts evita problemas de compilación de módulos nativos en algunos entornos, por ejemplo, Termux/Android — es inofensivo usarlo en cualquier lugar).

Ejecución independiente (para pruebas)

npm start

O prueba una sola llamada a una herramienta directamente a través de stdio sin ningún cliente MCP:

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

Configuración de Claude Desktop

Agrega esto a tu claude_desktop_config.json (Configuración → Desarrollador → Editar Config):

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

Reemplaza la ruta con la ruta absoluta real a build/index.js en tu máquina. Reinicia Claude Desktop después de editar la configuración.

Modo gratuito vs. de pago (x402)

Por defecto (BASEZAP_USE_X402=false o sin establecer), el servidor llama al endpoint gratuito de BaseZap (/api/agent). Establece BASEZAP_USE_X402=true para enrutar las llamadas a través del endpoint x402 de pago en su lugar ($0.001 USDC por llamada).

Importante: establecer BASEZAP_USE_X402=true por sí solo NO hace que el servidor pague automáticamente — recibirás un claro error HTTP 402 Payment Required en cada llamada a menos que hayas configurado el pago automático por separado (ver más abajo) o estés usando un cliente/puerta de enlace MCP que ya maneje el pago x402 por ti.

Opcional: pago automático x402

Consulta AUTOPAY.md para obtener una guía desde cero sobre cómo hacer que este servidor pague sus propias tarifas x402 automáticamente usando una billetera con fondos. Léelo atentamente antes de usarlo — implica poner una clave privada real en una variable de entorno, y un servidor de pago automático mal configurado puede gastar dinero real silenciosamente en cada llamada a una herramienta. NO está conectado por defecto, y debes entender exactamente qué hace antes de habilitarlo.

Contrato de solicitud verificado

La forma exacta de solicitud/respuesta en la que se basa este servidor se confirmó en vivo contra el endpoint real /api/agent (no se asumió de la documentación):

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

devuelve:

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

Nota: la API en sí misma usa nombres de campo en snake_case dentro de args — las entradas de herramientas MCP de este servidor usan camelCase amigable (amountUsdc) y traducen internamente, por lo que esto solo es relevante si estás modificando el servidor en sí.