Stables

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 55 tools across 12 categories, one for every operation documented on docs.stables.money(a contract test checks this, see below):

Customer Management

• create_customer - Create individual or business customers
• create_customer_onboarding_link - Create a customer and a hosted verification link in one call
• 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

Entitlements

• list_available_entitlements - Products and rails a customer can still apply for
• request_entitlements - Apply for entitlements (e.g. aed_local) for an existing customer
• submit_entitlement_requirements - Send the extra verification Stables asks for

Compliance requests (RFIs)

• list_rfis - The organisation's RFIs: what compliance needs before it releases a held payment or verification
• list_customer_rfis - One customer's RFIs
• get_rfi - One RFI, its requirements and how to answer each
• get_rfi_evidence_form - The form an evidence requirement asks for
• submit_rfi_evidence - Send the answers and documents for an evidence requirement
• get_kyc_capabilities - Verification capabilities a customer holds

Documents

• add_document - Attach an invoice, contract or other document to a transfer or a deposit
• list_documents - Documents on a transfer or a deposit
• get_document_download_url - Short-lived download link for a document
• delete_document - Remove a document

Quotes

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

Transfers

• validate_payment_method - Check payout details against a corridor's rules before transferring
• create_transfer - Execute a transfer using an active quote, paid by deposit or from your balance
• get_transfer - Check transfer status
• list_transfers - List transfers with filters

Saved Beneficiaries

• list_beneficiaries - Saved recipients and bank accounts, to pay by id with create_transfer
• get_beneficiary - One beneficiary's details and whether it still passes today's payout rules
• create_beneficiary - Save a recipient and bank account (validated like a transfer)
• archive_beneficiary - Archive a beneficiary so it can no longer be paid

Virtual Accounts

• create_virtual_account - Create virtual bank accounts for fiat deposits
• list_virtual_accounts - List virtual accounts for a customer, or across all customers
• update_virtual_account - Update virtual account settings
• register_route_payid - Register a PayID on an AUD payment route
• get_virtual_account_history - Get deposits and their payouts for a payment route
• update_route_destination - Change the payout wallet on an existing route
• list_route_whitelist / add_route_whitelist_account / update_route_whitelist_account - Source-account whitelisting for AUD routes

Balances

• get_balance - Your organisation's balance per asset and network
• get_balance_wallet / create_balance_wallet - The deposit wallet that tops up the balance
• list_balance_activity - Deposits credited to the balance
• list_pending_balance_deposits - Deposits held before crediting, and why
• list_whitelisted_wallets - Wallets allowed to fund the balance

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
• 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
• list_webhook_deliveries - Recent delivery attempts, status codes and retry state

Hosted server (recommended)

The server runs as a hosted service, so there is nothing to install. Point your MCP client at:

https://mcp.stables.money/mcp

and either send your Stables API key as a bearer token or sign in with OAuth. The key you get during onboarding is all you need: a sti_test_… key reaches sandbox, a sti_live_… key reaches production and moves real money. Clients that can't hold a key (Claude.ai, ChatGPT) sign in instead; see below.

Claude Code

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

Cursor, VS Code, Windsurf and other clients with a url field

{

"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 and other clients that sign in with OAuth

Add https://mcp.stables.money/mcp as a custom connector with no key. The client discovers the server's OAuth endpoints, registers itself, and sends you to a Stables page that asks two things: whether to connect sandbox or production, and permission for that client. You then sign in with your Stables dashboard account (and pick an organisation if you belong to several).

You choose Read only (the default) or Read and make changes; with read only, the agent can look but every tool that changes something is refused until you reconnect and allow changes. Agents connected this way can never create or revoke API keys. Every tool is labelled read-only or destructive, so clients such as Claude ask you before each change. Auth0 asks for your credentials (and a second factor) every time (an existing browser session is never reused for an agent connection) and, when you belong to several organisations, which one to use. On success the server creates an API key in that organisation, named after the client and the account that signed in (for example Claude via MCP (you@company.com)), and uses it for every call the client makes. Revoke it any time under Developer → API keys in the dashboard, which disconnects the client. Nothing else is stored: the sign-in token is used once to create the key and then dropped.

• Claude.ai / Claude Desktop: Settings → Connectors → Add custom connector, URL https://mcp.stables.money/mcp, leave the OAuth client fields on their defaults.
• ChatGPT: Settings → Connectors → Create (developer mode), MCP server URL https://mcp.stables.money/mcp, authentication OAuth.
• Claude Code without a key: claude mcp add --transport http stables https://mcp.stables.money/mcp, then /mcp to sign in.

The OAuth endpoints are standard: /.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server, /authorize, /oauth/token, /oauth/register. Client ID Metadata Documents and dynamic registration are both accepted; PKCE (S256) is required.

Running locally

The same server also runs as a local process over stdio, which is what npx stables-mcp-server does. Use this for a sti_local_… key against your own deployment, or when your client cannot reach the internet.

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:

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:

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.

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 source USDT + network, destination EUR + country, and destinationNetwork (swift or bank)
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=created or status=in_progress (statuses are lowercase)
2. Returns a formatted list of in-flight transfers

Setting up auto-payout

User: "Create a payment route for customer abc123 that pays AUD deposits out to my Polygon USDT wallet 0x..."

**AI (using MCP tools)