SpherePay

SpherePay MCP Server

A Model Context Protocol server for the SpherePay payment platform. Manage customers, bank accounts, wallets, transfers, virtual accounts, webhooks, and CCTP off-ramps directly from Claude.

Features

• 24 curated tools — 9 workflow tools for multi-step operations, 15 read-only tools for instant lookups
• Automatic retries with exponential backoff and rate limit handling
• Idempotency for transfers — duplicate requests are safely deduplicated
• PII redaction in logs — account numbers, routing numbers, and personal data are never logged
• Input validation at the tool boundary — IDs, currencies, networks, and amounts are validated before any API call
• Desktop Extension (.mcpb) for one-click Claude Desktop installation

Tools

Workflow Tools

| Tool | Description | |------|-------------| | onboard_customer | Create a customer (individual or business) and generate TOS/KYC verification links | | verify_customer | Two-step verification: send OTP, then verify with face recognition | | setup_funding | Create a bank account (USD/EUR) or crypto wallet for a customer | | execute_transfer | Transfer money between funding instruments with automatic idempotency | | onboard_business_rep | Create and verify a business representative | | setup_virtual_account | Create a virtual account for automatic fiat-to-stablecoin conversion | | setup_offloader_wallet | Create an offloader wallet for stablecoin-to-fiat off-ramp | | create_webhook | Subscribe to event notifications via HTTPS webhooks | | submit_cctp_offramp | Submit a CCTP burn transaction for cross-chain off-ramp redemption |

Read-Only Tools

| Tool | Description | |------|-------------| | get_customer / list_customers | Retrieve customer details and verification status | | get_transfer / list_transfers | Retrieve transfers with status, filter by customer/status/type | | get_bank_account / list_bank_accounts | Retrieve bank account details, filter by customer | | get_wallet / list_wallets | Retrieve wallet details, filter by customer | | get_virtual_account / list_virtual_accounts | Retrieve virtual account details and deposit instructions | | list_virtual_account_transfers | List deposits and conversions for a virtual account | | get_offloader_wallet / list_offloader_wallets | Retrieve offloader wallet details and off-ramp config | | get_webhook | Retrieve webhook details and delivery status | | get_event | Retrieve event details and webhook delivery records |

Supported Currencies and Networks

| Currency | Type | |----------|------| | usd, eur | Fiat | | usdc, usdt, eurc | Stablecoin |

| Network | Type | |---------|------| | ach, wire, sepa | Fiat rails | | ethereum, polygon, sol, base, arbitrum, tron, avalanche, optimism | Blockchain |

Installation

Prerequisites

• Python 3.12+
• A SpherePay API key (get one here)

Claude Desktop (stdio)

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "spherepay": {
      "command": "uvx",
      "args": ["spherepay-mcp"],
      "env": {
        "SPHEREPAY_BASE_URL": "https://api.sandbox.spherepay.co",
        "SPHEREPAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Desktop Extension

Download the latest .mcpb file from GitHub Releases and double-click to install in Claude Desktop.

Standalone

git clone https://github.com/danchev/spherepay-mcp.git
cd spherepay-mcp
uv sync
uv run spherepay-mcp

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SPHEREPAY_API_KEY | Yes | — | Your SpherePay API key (Bearer token) | | SPHEREPAY_BASE_URL | No | https://api.sandbox.spherepay.co | API base URL. Use https://api.spherepay.co for production | | SPHEREPAY_TIMEOUT | No | 30 | Request timeout in seconds | | SPHEREPAY_MAX_RETRIES | No | 3 | Max retry attempts for transient failures (429, 5xx) |

License

AGPL-3.0 License. See LICENSE for details.

<!-- mcp-name: io.github.danchev/spherepay -->