About SpherePay
SpherePay is an MCP server for managing payment-platform customers, funding instruments, transfers, and related operations from Claude. It combines multi-step workflows with read-only lookups and safeguards such as transfer idempotency and input validation.
Key features
- 01Customer onboarding and verification
- 02Bank account and wallet setup
- 03Transfers with idempotency
- 04Virtual accounts and off-ramps
- 05Webhook and event lookups
- 06Validated inputs and PII-redacted logs
Use cases
- 01Onboarding individual or business customers
- 02Setting up fiat or crypto funding
- 03Moving funds between instruments
- 04Tracking transfers and webhook events
MCP support
Exposes 24 SpherePay tools to MCP clients: workflow tools for multi-step operations and read-only tools for retrieving records. It can be connected to Claude Desktop or another compatible client.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx spherepay-mcpSPHEREPAY_API_KEYSecretYour SpherePay API key (Bearer token). Get one at https://dashboard.spherepay.coSPHEREPAY_BASE_URLAPI base URL. Use https://api.sandbox.spherepay.co for testing or https://api.spherepay.co for production.SPHEREPAY_TIMEOUTRequest timeout in seconds (default: 30)SPHEREPAY_MAX_RETRIESMaximum retry attempts for transient failures (default: 3)Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMESpherePay 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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.