# SpherePay MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) server for the [SpherePay](https://spherepay.co) 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](https://spherepay.co/dashboard))

### Claude Desktop (stdio)

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

```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](https://github.com/danchev/spherepay-mcp/releases) and double-click to install in Claude Desktop.

### Standalone

```bash
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](LICENSE) for details.

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