stables-mcp-server 1.4.0 → 2.1.0

package/README.md

@@ -1,6 +1,8 @@
 # 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, and others to manage customers, create quotes, execute transfers, and handle virtual accounts programmatically.
+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?
 
@@ -8,7 +10,7 @@ MCP (Model Context Protocol) is an open standard that provides a standardized wa
 
 ## Features
 
-This MCP server provides 25 tools across 7 categories:
+This MCP server provides 26 tools across 7 categories:
 
 ### Customer Management
 - `create_customer` - Create individual or business customers
@@ -31,9 +33,12 @@ This MCP server provides 25 tools across 7 categories:
 - `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
+- `get_virtual_account_history` - Get deposits and their payouts for a payment route
+- `update_route_destination` - Change the payout wallet on an existing route
+
+### Sandbox
+- `simulate_route_deposit` - Simulate a fiat deposit into a payment route (sandbox only)
+- `simulate_transfer_deposit` - Simulate the inbound crypto an off-ramp transfer awaits (sandbox only)
 
 ### API Keys
 - `create_api_key` - Create a new API key
@@ -45,9 +50,7 @@ This MCP server provides 25 tools across 7 categories:
 - `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)
+- `list_webhook_deliveries` - Recent delivery attempts, status codes and retry state
 
 ## Installation
 
@@ -69,10 +72,26 @@ 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`) |
+| `STABLES_API_URL` | No | API base URL. Defaults to the environment your key belongs to (see below). Must use HTTPS. |
+
+### Which environment you're talking to
+
+Stables keys carry their environment: `sti_test_…` is a sandbox key, `sti_live_…`
+is a production key, and the API refuses a key that arrives at the wrong
+environment. So you don't have to set a URL — leave `STABLES_API_URL` unset and
+the key decides:
+
+| Your key | Where requests go |
+|----------|-------------------|
+| `sti_test_…` | `https://api.sandbox.stables.money` |
+| `sti_live_…` | `https://api.stables.money` — **real money** |
+| `sti_local_…` or anything else | production, unless you set `STABLES_API_URL` |
+
+Setting `STABLES_API_URL` always wins, which is how you reach staging, dev or a
+local deployment.
+
+**Start with a sandbox key.** An agent holding a live key can move real money on
+your behalf; see [agent safety](https://docs.stables.money/get-started/getting-started/quickstart/building-with-ai/agent-safety).
 
 ## Usage
 
@@ -97,6 +116,29 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 Then restart Claude Desktop.
 
+### With Cursor, Codex, ChatGPT, or another MCP client
+
+Use the same command and environment variables in any MCP-compatible client:
+
+```json
+{
+  "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)
 
 ```bash
@@ -118,11 +160,11 @@ STABLES_API_KEY=your-api-key node build/index.js
 
 ### Creating a customer and getting a quote
 
-**User:** "Create a customer for john@example.com and get a quote to convert 1000 USDC to EUR"
+**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
+2. Calls `create_quote` with source USDT + network, destination EUR + country, and `destinationNetwork` (`swift` or `bank`)
 3. Returns customer details and quote information
 
 ### Checking transfer status
@@ -130,16 +172,24 @@ STABLES_API_KEY=your-api-key node build/index.js
 **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
+1. Calls `list_transfers` with `status=created` or `status=in_progress` (statuses are lowercase)
+2. Returns a formatted list of in-flight transfers
 
 ### Setting up auto-payout
 
-**User:** "Create a virtual USD account for customer abc123 that auto-pays to my Polygon USDC wallet 0x..."
+**User:** "Create a payment route for customer abc123 that pays AUD deposits out to my Polygon USDT wallet 0x..."
+
+**AI (using MCP tools):**
+1. Calls `create_virtual_account` with the customer ID, AUD source currency, and the Polygon destination (the payout address is mandatory)
+2. Returns the deposit instructions to share with the customer
+
+### Paying out to a European beneficiary
+
+**User:** "Pay 500 EUR to this German bank account"
 
 **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
+1. Collects the extra beneficiary details EUR requires — `recipientType`, a full address, and `dateOfBirth` for individuals — before doing anything else
+2. Calls `create_quote`, then `create_transfer` once a human approves
 
 ## Development
 
@@ -179,7 +229,7 @@ stables-mcp-server/
 │       ├── virtual-accounts.ts # Virtual account tools (6)
 │       ├── api-keys.ts       # API key tools (4)
 │       ├── webhooks.ts       # Webhook tools (3)
-│       └── notifications.ts  # Notification tools (1)
+│       └── sandbox.ts        # Sandbox deposit simulation (2)
 ├── package.json
 ├── tsconfig.json
 ├── vitest.config.ts
@@ -336,22 +386,6 @@ Update virtual account settings.
 | 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.
 
@@ -429,18 +463,6 @@ Delete a webhook subscription.
 |-----------|------|----------|-------------|
 | 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

package/build/index.js

@@ -32,7 +32,7 @@ import { registerTransferTools } from "./tools/transfers.js";
 import { registerVirtualAccountTools } from "./tools/virtual-accounts.js";
 import { registerApiKeyTools } from "./tools/api-keys.js";
 import { registerWebhookTools } from "./tools/webhooks.js";
-import { registerNotificationTools } from "./tools/notifications.js";
+import { registerSandboxTools } from "./tools/sandbox.js";
 // Validate environment
 const apiKey = process.env.STABLES_API_KEY;
 if (!apiKey) {
@@ -43,7 +43,7 @@ if (!apiKey) {
 // Create the MCP server
 const server = new McpServer({
     name: "stables-mcp-server",
-    version: "1.2.0",
+    version: "2.1.0",
     description: "Stables fiat-to-crypto API for AI agents - manage customers, quotes, transfers, and virtual accounts",
 });
 // Create the Stables API client
@@ -55,7 +55,7 @@ registerTransferTools(server, stablesClient);
 registerVirtualAccountTools(server, stablesClient);
 registerApiKeyTools(server, stablesClient);
 registerWebhookTools(server, stablesClient);
-registerNotificationTools(server, stablesClient);
+registerSandboxTools(server, stablesClient);
 // Start the server with STDIO transport
 async function main() {
     const transport = new StdioServerTransport();

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAErE,uBAAuB;AACvB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;IACZ,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;IACzE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,wBAAwB;AACxB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,oBAAoB;IAC1B,OAAO,EAAE,OAAO;IAChB,WAAW,EAAE,sGAAsG;CACpH,CAAC,CAAC;AAEH,gCAAgC;AAChC,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAC;AAE5C,qBAAqB;AACrB,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC7C,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC1C,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC7C,2BAA2B,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AACnD,mBAAmB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC3C,oBAAoB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC5C,yBAAyB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEjD,wCAAwC;AACxC,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,uBAAuB;AACvB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;IACZ,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;IACzE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,wBAAwB;AACxB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,oBAAoB;IAC1B,OAAO,EAAE,OAAO;IAChB,WAAW,EACT,sGAAsG;CACzG,CAAC,CAAC;AAEH,gCAAgC;AAChC,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAC;AAE5C,qBAAqB;AACrB,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC7C,kBAAkB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC1C,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC7C,2BAA2B,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AACnD,mBAAmB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC3C,oBAAoB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC5C,oBAAoB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE5C,wCAAwC;AACxC,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}