sphere-mcp

MCP server for Sphere Pay — 13 tools covering stablecoin contractor payouts, treasury sweeps, on-ramp / off-ramp virtual accounts, customer onboarding, KYC, and webhooks.

Designed primarily for contractor stablecoin payouts + treasury sweep (USDC → fiat bank, wallet → wallet). On-ramp and customer flows are secondary.

Any MCP-compatible AI agent (Claude Code, Cursor, ChatGPT, etc.) gets native access to Sphere's full payments stack.

Quick Start

git clone https://github.com/ExpertVagabond/sphere-mcp.git
cd sphere-mcp
npm install && npm run build

SPHERE_API_KEY=your_key node dist/index.js

Add to Claude Code

// ~/.claude/settings.json
{
  "mcpServers": {
    "sphere": {
      "command": "node",
      "args": ["/path/to/sphere-mcp/dist/index.js"],
      "env": {
        "SPHERE_API_KEY": "your_sphere_api_key"
      }
    }
  }
}

Environment Variables

| Var | Required | Default | Notes | |-----|----------|---------|-------| | SPHERE_API_KEY | yes | — | API key from the Sphere dashboard | | SPHERE_BASE_URL | no | https://api.spherepay.co | Override for sandbox / staging | | SPHERE_AUTH_HEADER | no | bearer | Set to x-api-key if Bearer is rejected | | SPHERE_TIMEOUT_MS | no | 30000 | Request timeout in milliseconds |

Tools (13)

| Tool | Purpose | |------|---------| | sphere_create_customer | Create individual or business customer | | sphere_get_customer | Retrieve a customer by ID | | sphere_list_customers | List customers with pagination | | sphere_create_kyc_link | Issue a hosted KYC link for a customer | | sphere_create_bank_account | Attach a bank account to a customer (ACH, wire, SEPA, PIX) | | sphere_list_bank_accounts | List bank accounts (filter by customer) | | sphere_create_transfer | Primary payout call — wallet/bank → wallet/bank, fiat or stablecoin | | sphere_get_transfer | Retrieve a transfer for status polling | | sphere_list_transfers | List transfers with status filter and pagination | | sphere_create_onramper_account | Provision a fiat virtual account that auto-converts to stablecoin | | sphere_create_offloader_wallet | Provision a stablecoin deposit address that auto-converts to fiat | | sphere_register_webhook | Subscribe an HTTPS URL to Sphere events | | sphere_verify_webhook_signature | Locally verify HMAC-SHA256 webhook signatures (no API call) |

Example: contractor payout

You: "Pay contractor cust_abc 500 USDC on Solana to their bank account ba_xyz"

Agent calls: sphere_create_transfer({
  amount: "500",
  customer: "cust_abc",
  source: { type: "wallet", id: "<treasury_wallet>", currency: "USDC", network: "solana" },
  destination: { type: "bankAccount", id: "ba_xyz", currency: "USD", network: "ach" }
})

→ { id: "tx_...", status: "processing", ... }

Architecture

src/
  index.ts                MCP server entry — registers all 13 tools
  client.ts               Sphere REST client (auth, timeout, error mapping)
  types.ts                Shared types
  tools/
    customers.ts          create / get / list customer
    kyc.ts                hosted KYC link
    bank-accounts.ts      create / list bank account
    transfers.ts          create / get / list transfer (primary payout)
    virtual-accounts.ts   onramper account, offloader wallet
    webhooks.ts           register webhook + local HMAC verifier

Notes on API Coverage

A few endpoint shapes (KYC link path, virtual-account required fields, webhook signature header / encoding) are documented loosely; those tools include // TODO: verify against live API notes and accept an extra passthrough object so you can supply any additional fields the API requires without waiting for a code change.

For canonical specs see docs.spherepay.co.

License

MIT