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.