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:

Variable	Required	Description
STABLES_API_KEY	Yes	Your Stables API key
STABLES_API_URL	No	API base URL (default: https://api.sandbox.stables.money). Must use HTTPS.
TWILIO_ACCOUNT_SID	No	Twilio Account SID (required for send_verification_sms)
TWILIO_AUTH_TOKEN	No	Twilio Auth Token (required for send_verification_sms)
TWILIO_PHONE_NUMBER	No	Twilio phone number to send from (required for send_verification_sms)

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 john@example.com 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.

Parameter	Type	Required	Description
email	string	Yes	Customer's email
customerType	"individual" | "business"	Yes	Type of customer
firstName	string	No	First name (for individuals)
lastName	string	No	Last name (for individuals)
companyName	string	No	Company name (for businesses)
entitlements	string[]	No	Entitlements to request (e.g., ["base_payout", "virtual_account"])

get_customer

Get customer details.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID

list_customers

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

get_verification_link

Generate a KYC verification link.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID
ttlInSecs	number	No	Link expiry in seconds (default: 1800)
successUrl	string	No	Redirect URL after successful verification
rejectUrl	string	No	Redirect URL after rejected verification

update_customer

Update customer details or entitlements.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID
email	string	No	Updated email
phone	string	No	Updated phone
firstName	string	No	Updated first name
lastName	string	No	Updated last name
entitlements	string[]	No	Updated entitlements

update_customer_metadata

Update customer metadata key-value pairs.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID
metadata	object	Yes	Key-value pairs to set

Quote Tools

create_quote

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

Parameter	Type	Required	Description
fromCurrency	"USDC" | "USDT"	Yes	Source cryptocurrency
fromAmount	string	Yes	Amount to convert
fromNetwork	"ethereum" | "polygon" | "polygon-amoy"	Yes	Blockchain network
toCurrency	string	Yes	Destination currency (e.g., "EUR")
toCountry	string	Yes	Destination country code (e.g., "GR")
paymentMethodType	"SWIFT" | "LOCAL"	Yes	Payment method for payout

get_quote

Get quote details.

Parameter	Type	Required	Description
quoteId	string	Yes	Quote ID

Transfer Tools

create_transfer

Execute a transfer from a quote.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID
quoteId	string	Yes	Quote ID to execute
accountHolderName	string	No	Bank account holder name
iban	string	No	IBAN
accountNumber	string	No	Bank account number
bankName	string	No	Bank name
bankCountry	string	No	Bank country code
bankCurrency	string	No	Payout currency
accountType	"savings" | "checking" | "payment"	No	Account type
swiftCode	string	No	SWIFT/BIC code
routingNumber	string	No	ABA routing number (US)
sortCode	string	No	Sort code (UK)
ifscCode	string	No	IFSC code (India)
bsbCode	string	No	BSB code (Australia)

get_transfer

Get transfer status.

Parameter	Type	Required	Description
transferId	string	Yes	Transfer ID

list_transfers

List transfers with filters.

Parameter	Type	Required	Description
status	string	No	Filter by status
type	string	No	Filter by type
customerId	string	No	Filter by customer
pageSize	number	No	Results per page
pageToken	string	No	Pagination token

Virtual Account Tools

create_virtual_account

Create a virtual bank account.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID
sourceCurrency	string	Yes	Currency (e.g., "USD")
depositHandlingMode	string	No	"auto_payout", "hold", or "manual"
destinationAddress	string	No	Crypto wallet address
destinationPaymentRail	string	No	Blockchain network
destinationCurrency	string	No	Stablecoin (default: "usdc")

list_virtual_accounts

List virtual accounts for a customer.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID
status	string	No	Filter by status
limit	number	No	Max results

update_virtual_account

Update virtual account settings.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID
virtualAccountId	string	Yes	Virtual account ID
depositHandlingMode	string	Yes	New deposit handling mode

deactivate_virtual_account

Deactivate a virtual account to prevent new deposits.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID
virtualAccountId	string	Yes	Virtual account ID

reactivate_virtual_account

Reactivate a previously deactivated virtual account.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID
virtualAccountId	string	Yes	Virtual account ID

get_virtual_account_history

Get activity history for a virtual account.

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID
virtualAccountId	string	Yes	Virtual account ID
limit	number	No	Max events to return
eventType	string	No	Filter by event type

API Key Tools

create_api_key

Create a new API key.

Parameter	Type	Required	Description
name	string	Yes	Descriptive name for the key
metadata	object	No	Optional metadata

list_api_keys

List all API keys.

Parameter	Type	Required	Description
pageSize	number	No	Results per page
pageToken	string	No	Pagination token

get_api_key

Get API key details.

Parameter	Type	Required	Description
apiKeyId	string	Yes	API key ID

revoke_api_key

Revoke an API key (permanent).

Parameter	Type	Required	Description
apiKeyId	string	Yes	API key ID

Webhook Tools

create_webhook

Subscribe to events via webhook.

Parameter	Type	Required	Description
name	string	Yes	Webhook name
url	string	Yes	HTTPS endpoint URL
eventTypes	string[]	Yes	Events to subscribe to
secret	string	No	HMAC-SHA256 signing secret

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.

Parameter	Type	Required	Description
webhookId	string	Yes	Webhook subscription ID

Notification Tools

send_verification_sms

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

Parameter	Type	Required	Description
customerId	string	Yes	Customer ID to send verification to
phone	string	No	Override phone number (uses customer's phone if not provided)
botName	string	No	Name of the assistant sending the message
verificationLinkTtlSecs	number	No	Verification link expiry in seconds (default: 1800)

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