Stables

Stables MCP 服务

一个 MCP（Model Context Protocol）服务，可将 Stables 法币到加密货币的 API 提供给 AI Agent 使用。借助它，Claude、ChatGPT、Cursor、Codex 等 AI 助手以及其他兼容 MCP 的客户端，可以通过编程方式管理客户、创建 USDC 和 USDT 报价、执行已获批准的转账，并管理虚拟账户。

可用它为 AI Agent 和 Agentic Commerce 构建稳定币支付工作流：付款、虚拟账户入金、资金调拨、法币出金和 webhook 对账。

什么是 MCP？

MCP（Model Context Protocol）是一种开放标准，提供将 AI 应用连接到外部工具和数据源的标准方式。可以把它想象成「AI 的 USB-C 接口」——任何支持 MCP 的 AI 都能使用任何 MCP 服务。

功能

此 MCP 服务提供 11 个类别共 51 个工具，涵盖 docs.stables.money 中记录的每项操作（下文提到的合约测试会对此进行检查）：

客户管理

• create_customer - 创建个人或企业客户
• create_customer_onboarding_link - 一次调用即可创建客户并生成托管验证链接
• get_customer - 获取客户详情和验证状态
• list_customers - 列出所有客户
• get_verification_link - 生成 KYC 验证链接
• update_customer - 更新客户详情和权限
• update_customer_metadata - 更新客户元数据键值对

权限

• list_available_entitlements - 列出客户仍可申请的产品和支付通道
• request_entitlements - 为现有客户申请权限（例如 aed_local）
• submit_entitlement_requirements - 提交 Stables 要求的额外验证材料

合规请求（RFI）

• list_rfis - 列出机构的 RFI：合规部门在释放被暂扣的付款或验证之前所需的信息
• list_customer_rfis - 列出某位客户的 RFI
• get_rfi - 获取单个 RFI、其要求以及每项要求的答复方式
• get_rfi_evidence_form - 获取 evidence 要求所需的表单
• submit_rfi_evidence - 提交 evidence 要求所需的答复和文件
• get_kyc_capabilities - 获取客户拥有的验证能力

文档

• add_document - 为转账或入金附加发票、合同或其他文件
• list_documents - 列出转账或入金的相关文件
• get_document_download_url - 获取文档的短时有效下载链接
• delete_document - 删除文档

报价

• create_quote - 获取汇率报价（USDC/USDT 兑换法币）
• get_quote - 查看报价状态和详情

转账

• validate_payment_method - 转账前，根据支付通道规则检查付款信息
• create_transfer - 使用有效报价执行转账，可通过入金付款或从余额中付款
• get_transfer - 查看转账状态
• list_transfers - 按筛选条件列出转账

虚拟账户

• create_virtual_account - 创建用于法币入金的虚拟银行账户
• list_virtual_accounts - 列出某位客户的虚拟账户，或列出所有客户的虚拟账户
• update_virtual_account - 更新虚拟账户设置
• register_route_payid - 在 AUD 付款路由上注册 PayID
• get_virtual_account_history - 获取支付路由的入金及其付款记录
• update_route_destination - 更改现有路由的付款钱包
• list_route_whitelist / add_route_whitelist_account / update_route_whitelist_account - 管理 AUD 路由的来源账户白名单

余额

• get_balance - 获取机构按资产和网络划分的余额
• get_balance_wallet / create_balance_wallet - 用于为余额充值的入金钱包
• list_balance_activity - 列出已计入余额的入金
• list_pending_balance_deposits - 列出计入余额前被暂扣的入金及原因
• list_whitelisted_wallets - 列出获准为余额充值的钱包

沙盒

• simulate_route_deposit - 模拟向支付路由存入法币（仅限沙盒）
• simulate_transfer_deposit - 模拟入金加密货币，这是出金转账所等待的资金（仅限沙盒）

API 密钥

• create_api_key - 创建新的 API 密钥
• list_api_keys - 列出所有 API 密钥
• get_api_key - 获取 API 密钥详情
• revoke_api_key - 撤销 API 密钥

Webhook

• create_webhook - 通过 Webhook 订阅事件
• list_webhooks - 列出所有 Webhook 订阅
• delete_webhook - 删除 Webhook 订阅
• list_webhook_deliveries - 查看近期投递尝试、状态码和重试状态

托管服务（推荐）

该服务以托管服务的形式运行，无需安装任何内容。将 MCP 客户端指向：

https://mcp.stables.money/mcp

然后将 Stables API 密钥作为 bearer token 发送，或通过 OAuth 登录。你在引导流程中获取的密钥就足够了：sti_test_… 密钥访问沙盒，sti_live_… 密钥访问生产环境并处理真实资金。无法保存密钥的客户端（Claude.ai、ChatGPT）可改为登录；请参阅下文。

Claude Code

claude mcp add --transport http stables https://mcp.stables.money/mcp --header "Authorization: Bearer ${STABLES_API_KEY}"

Cursor、VS Code、Windsurf 和其他具有 url 字段的客户端

{
  "mcpServers": {
    "stables": {
      "url": "https://mcp.stables.money/mcp",
      "headers": {
        "Authorization": "Bearer sti_test_..."
      }
    }
  }
}

Codex

[mcp_servers.stables]
url = "https://mcp.stables.money/mcp"
bearer_token_env_var = "STABLES_API_KEY"

Claude.ai、ChatGPT 和其他通过 OAuth 登录的客户端

将 https://mcp.stables.money/mcp 添加为自定义连接器，不填写密钥。客户端会发现服务的 OAuth 端点并注册自身，然后将你带到 Stables 页面，该页面会询问两项内容：连接沙盒还是生产环境，以及是否允许该客户端访问。随后，使用你的 Stables 控制面板账户登录（如果你属于多个组织，还需选择一个组织）。

你可以选择 只读（默认）或 读取并进行更改；选择只读时，Agent 可以查看信息，但在你重新连接并允许更改之前，所有会更改内容的工具都会被拒绝。以此方式连接的 Agent 永远无法创建或撤销 API 密钥。每个工具都会标明为只读或具有破坏性，因此 Claude 等客户端会在每次更改前询问你。Auth0 每次都会要求你提供凭据（以及第二重验证），不会重复使用现有浏览器会话来连接 Agent；如果你属于多个组织，还会询问要使用哪个组织。连接成功后，服务会在该组织中创建一个 API 密钥，名称由客户端名称和登录账户组成（例如 Claude via MCP ([email protected])），并将其用于客户端发起的每次调用。你可以随时在控制面板的 Developer → API keys 下撤销该密钥，这会断开客户端连接。除此之外，不会保存任何内容：登录令牌只用于创建密钥，之后便会丢弃。

• **Claude.ai / Claude Desktop：**Settings → Connectors → Add custom connector，URL 填写 https://mcp.stables.money/mcp，OAuth 客户端字段保留默认值。
• **ChatGPT：**Settings → Connectors → Create（developer mode），MCP 服务 URL 填写 https://mcp.stables.money/mcp，身份验证选择 OAuth。
• **不使用密钥的 Claude Code：**运行 claude mcp add --transport http stables https://mcp.stables.money/mcp，然后运行 /mcp 登录。

OAuth 端点符合标准：/.well-known/oauth-protected-resource/mcp、/.well-known/oauth-authorization-server、/authorize、/oauth/token、/oauth/register。同时支持客户端 ID 元数据文档和动态注册；必须使用 PKCE（S256）。

本地运行

同一服务也可以通过 stdio 作为本地进程运行，npx stables-mcp-server 就是这样运行的。可使用此方式通过 sti_local_… 密钥连接你自己的部署，或在客户端无法访问互联网时使用。

安装

# 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

配置

服务需要以下环境变量：

变量	必填	说明
STABLES_API_KEY	是	你的 Stables API 密钥
STABLES_API_URL	否	API 基础 URL。默认使用你的密钥所属环境（见下文）。必须使用 HTTPS。

你正在使用的环境

Stables 密钥会标明其环境：sti_test_… 是沙盒密钥，sti_live_… 是生产环境密钥，API 会拒绝在错误环境中使用的密钥。因此，你无需设置 URL —— 将 STABLES_API_URL 留空，由密钥决定：

你的密钥	请求发送至
sti_test_…	https://api.sandbox.stables.money
sti_live_…	https://api.stables.money — 真实资金
sti_local_… 或其他任何值	生产环境，除非你设置了 STABLES_API_URL

设置 STABLES_API_URL 后，它始终优先，因此你可以借此访问 staging、开发环境或本地部署。

请从沙盒密钥开始。 持有生产环境密钥的 Agent 可以代表你转移真实资金；请参阅Agent 安全。

用法

使用 Claude Desktop

添加到 ~/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"
      }
    }
  }
}

然后重启 Claude Desktop。

使用 Cursor、Codex、ChatGPT 或其他 MCP 客户端

在任何兼容 MCP 的客户端中使用相同的命令和环境变量：

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

Agent 安全

Stables 是金融基础设施。Agent 应创建报价、准备付款对象并核对 webhook，但在创建转账或进行其他资金转移之前，应要求获得明确的人工批准。执行交易操作前，请检查客户的 KYC/KYB 状态和权限；遇到制裁、司法管辖区不受支持、验证或合规失败时，应立即停止。

使用 MCP Inspector（用于测试）

# 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

直接执行

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

对话示例

创建客户并获取报价

用户：“为 [email protected] 创建客户，并获取将 1000 USDT 兑换成 EUR 的报价”

AI（使用 MCP 工具）：

1. 使用电子邮件和类型调用 create_customer
2. 使用源 USDT + 网络、目标 EUR + 国家/地区，以及 destinationNetwork（swift 或 bank）调用 create_quote
3. 返回客户详情和报价信息

查看转账状态

用户：“我所有待处理转账的状态是什么？”

AI（使用 MCP 工具）：

1. 使用 status=created 或 status=in_progress 调用 list_transfers（状态值为小写）
2. 返回格式化的进行中转账列表

设置自动付款

用户：“为客户 abc123 创建一条付款路线，将 AUD 入金付到我的 Polygon USDT 钱包 0x...”

AI（使用 MCP 工具）：

1. 使用客户 ID、AUD 源货币和 Polygon 目标调用 create_virtual_account（必须提供付款地址）
2. 返回可分享给客户的存款说明

向欧洲受益人付款

用户：“向这个德国银行账户支付 500 EUR”

AI（使用 MCP 工具）：

1. 先收集 EUR 付款所需的额外受益人信息 — recipientType、完整地址，以及个人的 dateOfBirth
2. 调用 create_quote，然后在人类批准后调用 create_transfer

运行托管服务

托管服务是 src/worker.ts（wrangler.toml）中的 Cloudflare Worker。它需要：

• OAUTH_KV：用于存储 OAuth 客户端、授权和令牌的 KV 命名空间。令牌和密钥以哈希形式存储；授权的 API 密钥经过加密，只有该授权的令牌才能解密。
• 变量 MCP_PUBLIC_URL、AUTH0_DOMAIN、AUTH0_CLIENT_ID：公共源地址、Auth0 自定义域名，以及「Stables MCP」常规 Web 应用（回调地址为 https://mcp.stables.money/callback）。
• 密钥 AUTH0_CLIENT_SECRET：该应用的密钥。
• 密钥 MCP_GATEWAY_SIGNING_SECRET：与 API 网关的 IP 授权器共享。Worker 没有固定的出口 IP，因此会为每个转发请求签名（X-Stables-Mcp-Signature），生产环境接受此签名以替代源 IP 检查。没有该密钥时，生产环境会拒绝通过托管服务发出的网关调用；沙盒不受影响。

wrangler secret put AUTH0_CLIENT_SECRET
wrangler secret put MCP_GATEWAY_SIGNING_SECRET

如果没有 OAUTH_KV，Worker 将仅使用 bearer 密钥运行，单元测试会以这种方式对其进行测试。

开发

# 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

项目结构

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 (7)
│       ├── entitlements.ts   # Entitlement tools (3)
│       ├── compliance.ts     # RFI and KYC capability tools (6)
│       ├── documents.ts      # Transfer and deposit document tools (4)
│       ├── quotes.ts         # Quote tools (2)
│       ├── transfers.ts      # Transfer tools (4)
│       ├── virtual-accounts.ts # Payment route tools (9)
│       ├── balances.ts       # Balance tools (6)
│       ├── api-keys.ts       # API key tools (4)
│       ├── webhooks.ts       # Webhook tools (3)
│       └── sandbox.ts        # Sandbox deposit simulation (2)
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── eslint.config.js
└── README.md

API 参考

客户工具

create_customer

创建新客户，用于 KYC 和转账。

参数	类型	必填	描述
email	string	是	客户的电子邮箱
customerType	"individual" | "business"	是	客户类型
firstName	string	否	名字（个人客户）
lastName	string	否	姓氏（个人客户）
companyName	string	否	公司名称（企业客户）
entitlements	string[]	否	要申请的权益（例如，["base_payout", "virtual_account"]）

get_customer

获取客户详情。

参数	类型	必填	描述
customerId	string	是	客户 ID

list_customers

列出已认证租户的所有客户。无需参数。

get_verification_link

生成 KYC 验证链接。

参数	类型	必填	描述
customerId	string	是	客户 ID
ttlInSecs	number	否	链接过期时间，单位为秒（默认值：1800）
successUrl	string	否	验证成功后的重定向 URL
rejectUrl	string	否	验证被拒后的重定向 URL

update_customer

更新客户详情或权益。

参数	类型	必填	描述
customerId	string	是	客户 ID
email	string	否	更新后的电子邮箱
phone	string	否	更新后的电话
firstName	string	否	更新后的名字
lastName	string	否	更新后的姓氏
entitlements	string[]	否	更新后的权益

update_customer_metadata

更新客户元数据键值对。

参数	类型	必填	描述
customerId	string	是	客户 ID
metadata	object	是	要设置的键值对

报价工具

create_quote

获取货币兑换报价（加密货币兑换为法定货币）。

参数	类型	必填	描述
fromCurrency	"USDC" | "USDT"	是	来源加密货币
fromAmount	string	是	要兑换的金额
fromNetwork	"ethereum" | "polygon" | "polygon-amoy"	是	区块链网络
toCurrency	string	是	目标货币（例如，"EUR"）
toCountry	string	是	目标国家/地区代码（例如，"GR"）
paymentMethodType	"SWIFT" | "LOCAL"	是	出款支付方式

get_quote

获取报价详情。

参数	类型	必填	描述
quoteId	string	是	报价 ID

转账工具

create_transfer

根据报价执行转账。

Parameter	Type	Required	Description
customerId	string	Yes	客户 ID
quoteId	string	Yes	要执行的报价 ID
accountHolderName	string	No	银行账户持有人姓名
iban	string	No	IBAN
accountNumber	string	No	银行账号
bankName	string	No	银行名称
bankCountry	string	No	银行国家/地区代码
bankCurrency	string	No	收款币种
accountType	"savings" | "checking" | "payment"	No	账户类型
swiftCode	string	No	SWIFT/BIC 代码
routingNumber	string	No	ABA 路由号码（美国）
sortCode	string	No	Sort 代码（英国）
ifscCode	string	No	IFSC 代码（印度）
bsbCode	string	No	BSB 代码（澳大利亚）

get_transfer

获取转账状态。

Parameter	Type	Required	Description
transferId	string	Yes	转账 ID

list_transfers

列出符合筛选条件的转账。

Parameter	Type	Required	Description
status	string	No	按状态筛选
type	string	No	按类型筛选
customerId	string	No	按客户筛选
pageSize	number	No	每页结果数
pageToken	string	No	分页令牌

虚拟账户工具

create_virtual_account

创建虚拟银行账户。

Parameter	Type	Required	Description
customerId	string	Yes	客户 ID
sourceCurrency	string	Yes	币种（例如，“USD”）
depositHandlingMode	string	No	"auto_payout"、"hold" 或 "manual"
destinationAddress	string	No	加密货币钱包地址
destinationPaymentRail	string	No	区块链网络
destinationCurrency	string	No	稳定币（默认值："usdc"）

list_virtual_accounts

列出客户的虚拟账户。

Parameter	Type	Required	Description
customerId	string	Yes	客户 ID
status	string	No	按状态筛选
limit	number	No	最大结果数

update_virtual_account

更新虚拟账户设置。

Parameter	Type	Required	Description
customerId	string	Yes	客户 ID
virtualAccountId	string	Yes	虚拟账户 ID
depositHandlingMode	string	Yes	新的存款处理模式

get_virtual_account_history

获取虚拟账户的活动历史记录。

Parameter	Type	Required	Description
customerId	string	Yes	客户 ID
virtualAccountId	string	Yes	虚拟账户 ID
limit	number	No	返回的最大事件数
eventType	string	No	按事件类型筛选

API 密钥工具

create_api_key

创建新的 API 密钥。

Parameter	Type	Required	Description
name	string	Yes	密钥的描述性名称
metadata	object	No	可选元数据

list_api_keys

列出所有 API 密钥。

Parameter	Type	Required	Description
pageSize	number	No	每页结果数
pageToken	string	No	分页令牌

get_api_key

获取 API 密钥详情。

Parameter	Type	Required	Description
apiKeyId	string	Yes	API 密钥 ID

revoke_api_key

撤销 API 密钥（永久）。

Parameter	Type	Required	Description
apiKeyId	string	Yes	API 密钥 ID

Webhook 工具

create_webhook

通过 webhook 订阅事件。

Parameter	Type	Required	Description
name	string	是	Webhook 名称
url	string	是	HTTPS 端点 URL
eventTypes	string[]	是	要订阅的事件
secret	string	否	HMAC-SHA256 签名密钥

可用事件类型：

• 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

列出所有 webhook 订阅。无需参数。

delete_webhook

删除 webhook 订阅。

Parameter	Type	Required	Description
webhookId	string	是	Webhook 订阅 ID

安全

• API 密钥仅从环境变量读取
• API URL 必须使用 HTTPS（启动时强制检查）
• 不向 stderr 输出调试日志（否则会破坏 MCP STDIO 传输）
• 使用 Zod schema 验证所有输入
• 请求超时（30s）可防止连接挂起
• 对暂时性故障进行自动重试，并采用指数退避

许可证

MIT

链接

• Stables API 文档
• npm 包
• Model Context Protocol
• MCP TypeScript SDK