Stables MCP Server

Stables MCP Server

Enables AI agents to manage stablecoin payments including customer management, quotes, transfers, virtual accounts, and webhooks via the Stables API.

Category
访问服务器

README

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

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选