Stables MCP Server

An MCP (Model Context Protocol) server that exposes the Stables fiat-to-crypto API to AI agents. This allows AI assistants like Claude, ChatGPT, Cursor, Codex, and other MCP-compatible clients to manage customers, create USDC and USDT quotes, execute approved transfers, and handle virtual accounts programmatically.

Use it to build stablecoin payment workflows for AI agents and agentic commerce: payouts, virtual account deposits, treasury movement, fiat off-ramping, and webhook reconciliation.

What is MCP?

MCP (Model Context Protocol) is an open standard that provides a standardized way to connect AI applications to external tools and data sources. Think of it like a "USB-C port for AI" - any AI that supports MCP can use any MCP server.

Features

This MCP server provides 25 tools across 7 categories:

Customer Management

• create_customer - Create individual or business customers
• get_customer - Get customer details and verification status
• list_customers - List all customers
• get_verification_link - Generate KYC verification links
• update_customer - Update customer details and entitlements
• update_customer_metadata - Update customer metadata key-value pairs

Quotes

• create_quote - Get exchange rate quotes (USDC/USDT to fiat)
• get_quote - Check quote status and details

Transfers

• create_transfer - Execute a transfer using an active quote
• get_transfer - Check transfer status
• list_transfers - List transfers with filters

Virtual Accounts

• create_virtual_account - Create virtual bank accounts for fiat deposits
• list_virtual_accounts - List virtual accounts for a customer
• update_virtual_account - Update virtual account settings
• deactivate_virtual_account - Deactivate a virtual account
• reactivate_virtual_account - Reactivate a deactivated virtual account
• get_virtual_account_history - Get activity history for a virtual account

API Keys

• create_api_key - Create a new API key
• list_api_keys - List all API keys
• get_api_key - Get API key details
• revoke_api_key - Revoke an API key

Webhooks

• create_webhook - Subscribe to events via webhook
• list_webhooks - List all webhook subscriptions
• delete_webhook - Delete a webhook subscription

Notifications

• send_verification_sms - Send a KYC verification link to a customer via SMS (requires Twilio)

Installation

# Install from npm
npm install -g stables-mcp-server

# Or clone and build from source
git clone https://github.com/stables-money/mcp-server.git
cd mcp-server
npm install
npm run build

Configuration

The server requires the following environment variables:

Usage

With Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "stables": {
      "command": "npx",
      "args": ["stables-mcp-server"],
      "env": {
        "STABLES_API_KEY": "your-api-key",
        "STABLES_API_URL": "https://api.sandbox.stables.money"
      }
    }
  }
}

Then restart Claude Desktop.

With Cursor, Codex, ChatGPT, or another MCP client

Use the same command and environment variables in any MCP-compatible client:

{
  "mcpServers": {
    "stables": {
      "command": "npx",
      "args": ["stables-mcp-server"],
      "env": {
        "STABLES_API_KEY": "your-api-key",
        "STABLES_API_URL": "https://api.sandbox.stables.money"
      }
    }
  }
}

Agent safety

Stables is financial infrastructure. Agents should create quotes, prepare payment objects, and reconcile webhooks, but should require explicit human approval before creating transfers or other money movement. Check customer KYC/KYB status and entitlements before transactional actions, and treat sanctions, unsupported jurisdiction, verification, or compliance failures as hard stops.

With MCP Inspector (for testing)

# Set environment variables
export STABLES_API_KEY=your-api-key
export STABLES_API_URL=https://api.sandbox.stables.money

# Run the inspector
npm run inspect

Direct Execution

STABLES_API_KEY=your-api-key node build/index.js

Example Conversations

Creating a customer and getting a quote

User: "Create a customer for [email protected] and get a quote to convert 1000 USDT to EUR"

AI (using MCP tools):

1. Calls create_customer with email and type
2. Calls create_quote with USDC, amount, EUR destination, network, country, and payment method
3. Returns customer details and quote information

Checking transfer status

User: "What's the status of all my pending transfers?"

AI (using MCP tools):

1. Calls list_transfers with status=PENDING
2. Returns formatted list of pending transfers

Setting up auto-payout

User: "Create a virtual USD account for customer abc123 that auto-pays to my Polygon USDC wallet 0x..."

AI (using MCP tools):

1. Calls create_virtual_account with customer ID, USD currency, and Polygon destination
2. Returns virtual account details with deposit instructions

Development

# Watch mode for development
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Run linter
npm run lint

# Format code
npm run format

# Test with MCP Inspector
npm run inspect

Project Structure

stables-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── lib/
│   │   ├── stables-client.ts # Stables API client (with retries, timeouts)
│   │   └── stables-client.test.ts
│   └── tools/
│       ├── customers.ts      # Customer management tools (6)
│       ├── quotes.ts         # Quote tools (2)
│       ├── transfers.ts      # Transfer tools (3)
│       ├── virtual-accounts.ts # Virtual account tools (6)
│       ├── api-keys.ts       # API key tools (4)
│       ├── webhooks.ts       # Webhook tools (3)
│       └── notifications.ts  # Notification tools (1)
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── eslint.config.js
└── README.md

API Reference

Customer Tools

#### create_customer Create a new customer for KYC and transfers.

#### get_customer Get customer details.

#### list_customers List all customers for the authenticated tenant. No parameters required.

#### get_verification_link Generate a KYC verification link.

#### update_customer Update customer details or entitlements.

#### update_customer_metadata Update customer metadata key-value pairs.

Quote Tools

#### create_quote Get a quote for currency exchange (crypto to fiat).

#### get_quote Get quote details.

Transfer Tools

#### create_transfer Execute a transfer from a quote.

#### get_transfer Get transfer status.

#### list_transfers List transfers with filters.

Virtual Account Tools

#### create_virtual_account Create a virtual bank account.

#### list_virtual_accounts List virtual accounts for a customer.

#### update_virtual_account Update virtual account settings.

#### deactivate_virtual_account Deactivate a virtual account to prevent new deposits.

#### reactivate_virtual_account Reactivate a previously deactivated virtual account.

#### get_virtual_account_history Get activity history for a virtual account.

API Key Tools

#### create_api_key Create a new API key.

#### list_api_keys List all API keys.

#### get_api_key Get API key details.

#### revoke_api_key Revoke an API key (permanent).

Webhook Tools

#### create_webhook Subscribe to events via webhook.

Available event types:

• WEBHOOK_EVENT_TYPE_CUSTOMER_CREATED
• WEBHOOK_EVENT_TYPE_CUSTOMER_UPDATED
• WEBHOOK_EVENT_TYPE_KYC_STATUS_CHANGED
• WEBHOOK_EVENT_TYPE_PAYMENT_CREATED
• WEBHOOK_EVENT_TYPE_PAYMENT_STATUS_CHANGED
• WEBHOOK_EVENT_TYPE_QUOTE_CREATED
• WEBHOOK_EVENT_TYPE_QUOTE_EXPIRED
• WEBHOOK_EVENT_TYPE_VA_DEPOSIT_RECEIVED
• WEBHOOK_EVENT_TYPE_VA_PAYOUT_COMPLETED
• WEBHOOK_EVENT_TYPE_VA_PAYOUT_FAILED
• WEBHOOK_EVENT_TYPE_ALL

#### list_webhooks List all webhook subscriptions. No parameters required.

#### delete_webhook Delete a webhook subscription.

Notification Tools

#### send_verification_sms Send a KYC verification link to a customer via SMS. Requires Twilio environment variables.

Security

• API keys are only read from environment variables
• HTTPS required for API URL (enforced at startup)
• No debug logging to stderr (would corrupt MCP STDIO transport)
• All inputs are validated with Zod schemas
• Request timeouts (30s) prevent hung connections
• Automatic retries with exponential backoff for transient failures

License

MIT

Links

• Stables API Documentation
• npm Package
• Model Context Protocol
• MCP TypeScript SDK