MCP

Connect Claude, Cursor, Codex, VS Code and any other MCP-compatible client to the Stables API through the Model Context Protocol. An agent connected this way can onboard customers, price and execute USDT payouts, open payment routes for fiat deposits, and reconcile webhooks, all through the same API your code uses.

MCP (Model Context Protocol) is an open standard for connecting AI applications to external tools, like a USB-C port for AI: any client that speaks MCP can use any MCP server.

For agent-specific discovery and safety guidance, see AI agents and Agent safety.

Connect in one stepCopy Anchor Link

The Stables MCP server is hosted. There is nothing to install and nothing to run. Point your client at:

https://mcp.stables.money/mcp

There are two ways to authenticate:

• Sign in with your Stables account. Clients that support MCP sign-in (OAuth), such as Claude.ai, Claude Desktop and ChatGPT, open a Stables login page and need no API key. See Claude.ai and Claude Desktop and ChatGPT.
• Send an API key as a bearer token. Everything else, including Claude Code, Cursor, VS Code, Windsurf and Codex.

With an API key, the hosted server takes sandbox keys (sti_test_…), which reach api.sandbox.stables.money, where no real money moves.

Production only accepts calls from allowlisted addresses, and the hosted server's addresses are not on that list, so it refuses live keys (sti_live_…) with an explanation. For production, either connect by signing in (Claude, ChatGPT), or run the server locally from an allowlisted machine with your live key.

Start with a sandbox key. The hosted server stores no credentials of its own; every request carries yours, and a request without a valid key is refused before it reaches the API.

Claude CodeCopy Anchor Link

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 fieldCopy Anchor Link

Add this to the client's MCP configuration (~/.cursor/mcp.json, .vscode/mcp.json, and so on):

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

CodexCopy Anchor Link

In ~/.codex/config.toml:

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

Claude.ai and Claude DesktopCopy Anchor Link

These clients connect by signing in, so there is no key to copy.

1. In Claude, open Settings > Connectors and choose Add custom connector.
2. Name it Stables, enter https://mcp.stables.money/mcp as the URL and choose Add.
3. Choose Connect on the new connector. A Stables page opens: pick Sandbox or Production, choose Read only or Read and make changes, then Allow and sign in.
4. Sign in with the account you use for the Stables dashboard. If you belong to more than one organization, pick the one the agent should act for.

When you allow access, Stables creates an API key for the connection in that environment, named after the client and your email (for example Claude via MCP ([email protected])). It is listed with your other keys in the dashboard. Revoke it there, or use Disconnect on the AI agents page, to cut the connection off; removing the connector in Claude alone does not revoke the key. Connecting the same client again replaces its earlier key, which is revoked for you.

ChatGPTCopy Anchor Link

ChatGPT connects by signing in too. Custom connectors need developer mode, which is available on paid plans; on a Business or Enterprise workspace an admin may need to allow it first.

1. In ChatGPT on the web, open Settings and turn on Developer mode (under the apps or plugins settings, in Advanced settings).
2. Create a new plugin: name it Stables, enter https://mcp.stables.money/mcp as the URL, choose OAuth for authentication, and create it.
3. A Stables page opens: pick Sandbox or Production, choose the access, then Allow and sign in, and pick your organization.
4. In a chat, turn on Stables from the + menu before asking for something.

The key Stables creates is named ChatGPT via MCP ([email protected]) and works exactly like Claude's: listed in the dashboard, revoked there.

Other clients that support MCP sign-in can connect the same way. Claude.ai, Claude Desktop and ChatGPT are the ones we have tested.

Try itCopy Anchor Link

Start a new conversation and ask: "List my Stables customers". The agent calls list_customers and shows what is in the environment you connected to.

Run it locally insteadCopy Anchor Link

The same server is published to npm and runs as a local process over stdio. Use this for production API keys (from a machine whose address is on your production allowlist), when your client only supports local servers, when you work against a sti_local_… key and your own deployment, or when the client cannot reach the internet. The AI agents page in the production dashboard gives each coding tool this local setup with a key filled in.

Requirements: Node.js 18 or later.

For example, to run it locally in Claude Desktop instead of signing in, add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then quit and reopen Claude Desktop:

{
  "mcpServers": {
    "stables": {
      "command": "npx",
      "args": ["stables-mcp-server"],
      "env": {
        "STABLES_API_KEY": "sti_test_..."
      }
    }
  }
}

Source and issues: github.com/stables-money/mcp-server.

ToolsCopy Anchor Link

The server exposes 26 tools. Each one mirrors a documented Stables API endpoint and nothing else; the reference below is generated from the server's own tool schemas, so it matches what your client sees.

CustomersCopy Anchor Link

create_customerCopy Anchor Link

Create a new customer in Stables for KYC verification and transfers. Use 'individual' for personal accounts or 'business' for company accounts. Include entitlements like 'base_payout' to enable transactions.

get_customerCopy Anchor Link

Get details about a specific customer including their verification status

list_customersCopy Anchor Link

List all customers for the authenticated tenant

No parameters.

get_verification_linkCopy Anchor Link

Generate a KYC verification link for a customer. The customer must complete verification before they can make transfers.

update_customerCopy Anchor Link

Update customer details, entitlements, or verification information

update_customer_metadataCopy Anchor Link

Update customer metadata key-value pairs

QuotesCopy Anchor Link

create_quoteCopy Anchor Link

Get a quote for a currency exchange: the rate, the fees, and what the customer receives. Quotes are short-lived, so create one immediately before the transfer. Off-ramp converts a stablecoin to fiat (source network required, destination country required); on-ramp converts fiat to a stablecoin (destination address required). Set preview to price without committing.

get_quoteCopy Anchor Link

Get details about an existing quote including its current status

TransfersCopy Anchor Link

create_transferCopy Anchor Link

Execute a transfer using an active quote. The quote must not be expired. This initiates real money movement, so get explicit human approval first. For payouts in AED, CAD, EUR, GBP, MXN, USD you must also supply recipientType, the full beneficiary address, and dateOfBirth when the recipient is an individual.

get_transferCopy Anchor Link

Get the current status and details of a transfer

list_transfersCopy Anchor Link

List transfers with optional filters for status, type, or customer

Payment routesCopy Anchor Link

create_virtual_accountCopy Anchor Link

Create a payment route (virtual bank account) so a customer can receive fiat deposits that convert to a stablecoin and pay out to a wallet. The payout destination is mandatory: the API refuses a fiat-to-crypto route without one. Deposit handling is set server-side and defaults to auto_payout; change it afterwards with update_virtual_account.

list_virtual_accountsCopy Anchor Link

List all virtual accounts for a customer

update_virtual_accountCopy Anchor Link

Update virtual account settings (e.g., deposit handling mode)

get_virtual_account_historyCopy Anchor Link

Get the activity history for a virtual account (deposits, payouts, etc.)

update_route_destinationCopy Anchor Link

Change the payout wallet on an existing payment route. Deposits after this point are paid out to the new address; use it when a customer rotates wallets rather than creating a second route.

SandboxCopy Anchor Link

simulate_route_depositCopy Anchor Link

SANDBOX ONLY. Simulate a fiat deposit into a payment route so you can watch the conversion and payout complete without a real bank transfer. Fails on production.

simulate_transfer_depositCopy Anchor Link

SANDBOX ONLY. Simulate the customer sending the crypto an off-ramp transfer is waiting on, so the transfer can progress to payout without an on-chain payment. Fails on production.

API keysCopy Anchor Link

create_api_keyCopy Anchor Link

Create a new API key for accessing the Stables API. The secret key is only shown once on creation - save it immediately.

list_api_keysCopy Anchor Link

List all API keys for the current account

get_api_keyCopy Anchor Link

Get details about a specific API key

revoke_api_keyCopy Anchor Link

Revoke an API key. This permanently disables the key and cannot be undone.

WebhooksCopy Anchor Link

create_webhookCopy Anchor Link

Subscribe to Stables events via webhook. You'll receive POST requests to your URL when events occur.

Event types are dotted and lowercase. Use 'all' to receive everything.

Security: Set a secret to enable HMAC-SHA256 signature verification via X-Webhook-Signature header.

list_webhooksCopy Anchor Link

List all webhook subscriptions for the current account

No parameters.

delete_webhookCopy Anchor Link

Delete a webhook subscription. You will stop receiving events at this endpoint.

list_webhook_deliveriesCopy Anchor Link

List recent webhook delivery attempts with their HTTP status and retry state. This is the first place to look when an integration is not receiving events: it shows whether Stables sent them and what the endpoint answered.

Example workflowsCopy Anchor Link

Onboard a customer

"Create an individual customer for [email protected] with the base_payout entitlement and give me a KYC link"

The agent calls create_customer, then get_verification_link for the new customer, and returns a link to share. Links expire after 30 minutes by default.

Price and execute a payout

"Quote 500 USDT on Polygon to EUR for customer abc123"

The agent calls create_quote and shows the rate, the fees and what the beneficiary receives, along with when the quote expires. Quotes are short-lived, so create one immediately before the transfer.

"Execute it to IBAN GR16 0110 1250 0000 0001 2300 695 at Alpha Bank, account holder Maria Papadopoulou"

The agent calls create_transfer with the quote and the beneficiary details, and returns the transfer ID, its status and the wallet address the USDT must be sent to. Some currencies require more beneficiary detail than others; the tool description lists what each currency needs.

Open a payment route

"Create a USD payment route for customer abc123 that pays out USDT on Base to 0x…"

The agent calls create_virtual_account and returns the deposit instructions. Later, "change the payout wallet on that route" calls update_route_destination, and "show me the deposit history" calls get_virtual_account_history.

Test a deposit in sandbox

"Simulate a 250 USD deposit into that route"

The agent calls simulate_route_deposit, which drives the route to a terminal state without a real bank payment. Sandbox only.

Reconcile webhooks

"Set up a webhook at https://example.com/stables that fires when transfers change status"

The agent calls create_webhook with transfer.updated.status_transitioned. If events stop arriving, "show me recent webhook deliveries" calls list_webhook_deliveries, the first place to look.

SecurityCopy Anchor Link

• With an API key, the hosted server holds no credentials. Your key travels with each request and is only ever forwarded to the Stables environment it belongs to.
• With sign-in, the key created for the connection is stored encrypted by the hosted server and used only for that connection's requests. It appears in your dashboard like any other key and can be revoked there.
• A key is never accepted in the URL, only in the Authorization or X-Api-Key header.
• Every write carries an idempotency key, built once per call, so a retried request cannot submit a payout twice.
• Create a separate API key per agent (sign-in does this for you) and revoke it from the dashboard when the agent is retired. An agent holding a sti_live_ key can move real money on your behalf; read Agent safety before going live.
• Keep human confirmation on for create_transfer and other money-moving tools in your client.

TroubleshootingCopy Anchor Link

401 from mcp.stables.money with "error": "unauthorized"

The request reached the hosted server without a usable key. Check that the Authorization: Bearer header is set and that the key starts with sti_test_. A live key (sti_live_) is refused with "Production API keys can't be used through the hosted server": sign in instead, or run the server locally from an allowlisted machine. A sti_local_ key cannot be routed by the hosted server either; run it locally with STABLES_API_URL.

"Invalid or missing authorization credentials" inside a tool result

The key reached the Stables API and was refused there. It has been revoked, or it belongs to the other environment. Check the key in the dashboard.

A local server's calls to production are refused

Production only accepts calls from allowlisted addresses. Run the server from a machine whose address is on your production allowlist, or ask Stables to add it.

Quote expired before the transfer

Quotes have a short lifetime. Create a new quote and execute the transfer straight away.

Local server not appearing in Claude Desktop

Check that the config file is valid JSON, that STABLES_API_KEY is set in the env block, and that you fully quit Claude Desktop (Cmd+Q) before reopening it. Run npx stables-mcp-server@latest once in a terminal to confirm Node can download and start it.