spherepay-mcp 0.0.1

SpherePay MCP server - curated Model Context Protocol tools for the SpherePay API

SpherePay MCP Server

A curated Model Context Protocol server for the SpherePay payment platform. Exposes 13 tools (5 workflow + 8 read-only) for managing customers, bank accounts, wallets, and transfers directly from AI assistants like Claude.

Built with a hexagonal architecture that separates domain logic, application workflows, and API transport for testability and reliability.

Features

• Workflow tools for multi-step operations (customer onboarding, verification, funding setup, transfers, business rep onboarding)
• Read-only tools for instant lookups (get/list customers, transfers, bank accounts, wallets)
• Reliability built in: automatic retries with exponential backoff, rate limit handling, idempotency keys for transfers
• Security-first: PII redaction in logs, production environment guardrail, no destructive operations exposed
• Desktop Extension packaging (.mcpb) for Claude Desktop

Architecture

src/spherepay_mcp/
  domain/             # Value objects, enums, validation
    value_objects.py  # Currency, Network, CustomerId, Amount, ApiError
  application/        # Workflow orchestration services
    customer_onboarding.py
    funding_instrument.py
    transfer_workflow.py
    business_rep.py
  ports/              # Protocol interfaces (outbound)
    spherepay_gateway.py
  adapters/           # HTTP client, reliability policy
    spherepay_client.py
    reliability.py
  interfaces/         # MCP tool registration, route config
    tools.py
    route_config.py
  server.py           # Composition root
  config.py           # Environment configuration

LLM Client --> Tool Layer --> Service Layer --> Gateway Protocol --> HTTP Adapter --> SpherePay API
                                                     ^
                                                     |
                                              ReliabilityPolicy
                                           (retry, backoff, idempotency)

Tools

Workflow Tools (multi-step operations)

Tool	Description
onboard_customer	Create customer + generate TOS/KYC verification links
verify_customer	OTP verification + face verification + submit
setup_funding	Create bank account or crypto wallet for a customer
execute_transfer	Transfer money with automatic idempotency
onboard_business_rep	Create and verify a business representative

Read-Only Tools (instant lookups)

Tool	Description
get_customer / list_customers	Retrieve customer details
get_transfer / list_transfers	Retrieve transfer details with filters
get_bank_account / list_bank_accounts	Retrieve bank account details
get_wallet / list_wallets	Retrieve wallet details

Quickstart

Prerequisites

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

Install

# Clone and install
git clone https://github.com/danchev/spherepay-mcp.git
cd spherepay-mcp
uv sync

Configure

# Required
export SPHEREPAY_API_KEY="your_api_key_here"

# Optional (defaults shown)
export SPHEREPAY_BASE_URL="https://api.sandbox.spherepay.co"
export SPHEREPAY_TIMEOUT="30"
export SPHEREPAY_MAX_RETRIES="3"

# Required for production use
export SPHEREPAY_CONFIRM_PRODUCTION="true"

Run

# As MCP server (stdio transport)
uv run spherepay-mcp

# Or directly
uv run python -m spherepay_mcp

Claude Desktop Configuration

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

{
  "mcpServers": {
    "spherepay": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/spherepay-mcp", "spherepay-mcp"],
      "env": {
        "SPHEREPAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Or install the Desktop Extension (.mcpb) for a GUI-based setup:

python scripts/build_mcpb.py --output dist/
# Double-click the .mcpb file to install in Claude Desktop

Development

# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov

# Lint
uv run ruff check src/ tests/
uv run pyright src/

Supported Currencies and Networks

Currency	Type
usd, eur	Fiat
usdc, usdt, eurc	Crypto

Network	Type
ach, wire, sepa	Fiat
ethereum, polygon, sol, base, arbitrum, tron, avalanche, optimism	Crypto

ADR Index

Architectural decisions are documented in docs/adr/:

ADR	Title	Status
0001	Curated OpenAPI (not full mirror)	Accepted
0002	Hexagonal workflow-centric architecture	Accepted
0003	Safe exposure via route maps and visibility	Accepted
0004	Reliability policy, idempotency, rate limits	Accepted
0005	Workflow tool composition over atomic endpoints	Accepted
0006	OpenAPI spec management and drift prevention	Accepted
0007	Desktop extension packaging strategy	Accepted
0008	User config and secrets management	Accepted
0009	MCPB bundle structure and entry point	Accepted
0010	Desktop extension spec alignment	Accepted
0011	Critical runtime fixes	Accepted
0012	Security hardening	Accepted
0013	Domain validation at tool boundary	Proposed
0014	Structured logging and request tracing	Proposed
0015	MCP resources for LLM discovery	Proposed

License

MIT