@stablecoinx/mcp

MCP server for the StablecoinX merchant API. Log in once via thirdweb email-OTP, then drive merchant CRUD, API keys, payment sessions, paymaster clients/allowlist, and webhooks on the merchant's behalf from any MCP client (Claude Code, Claude Desktop, Cursor, and others). Ships a bundled skill for end-to-end payment-gateway integration.

• stdio server, runs locally; all credentials stay on your machine, encrypted at rest.
• Targets the public StablecoinX harness, reachable without VPN — no endpoint, client ID, origin, or chain to configure.
• npm: @stablecoinx/mcp · MCP Registry: io.github.e2xlabs/stablecoinx-mcp

Quick start

npx @stablecoinx/mcp setup

This installs the stablecoinx skill into ~/.claude/skills and registers the MCP (claude mcp add, user scope) with a freshly generated state passphrase. The harness endpoint, thirdweb client, origin, and login chain are baked into the package — nothing else to configure. Restart your MCP client afterwards.

Prefer natural language? In your MCP client, ask "set up StablecoinX payments" - it runs the bundled skill, which drives this MCP.

Manual install

claude mcp add stablecoinx-mcp -s user \
  -e SCX_STATE_PASSPHRASE="$(openssl rand -hex 16)" \
  -- npx -y @stablecoinx/mcp

Requires Node.js 22.19 or later. SCX_STATE_PASSPHRASE is the only required input — it encrypts the local state file at rest; pick any string. The harness API URL, thirdweb client ID, request origin, and login chain are constants baked into the package. The setup command and the claude mcp add form above use Claude Code's claude CLI; other MCP clients register the server through their own config.

Harness

The MCP talks only to the public StablecoinX harness (api.harness.stablecoinx.com). The login smart account is created on Base; its address is deterministic across chains. Sandbox vs live settlement is determined server-side by the harness (per the merchant account) — there is nothing chain- or environment-related to set on the client.

Two different gas sponsorships are involved, and they are unrelated:

• The MCP's own login account (thirdweb in-app wallet + smart account) is sponsored by thirdweb. Nothing to configure, and it does not touch the merchant's StablecoinX gas balance.
• The StablecoinX paymaster sponsors your dApp users' operations through https://api.harness.stablecoinx.com/v1/paymaster/rpc with a pmc_* client id. The paymaster_* tools manage those clients, the contract allowlist, deny rules, spend limits, usage, the activity feed, the merchant overview and the gas balance; the skill's integrate-paymaster subcommand wires a dApp to it. Networks, contract addresses and the full error table: paymaster llms-full.txt.

floYsh / Yield as a Service

floYsh is StablecoinX's Yield as a Service (YaaS): a branded stablecoin-yield site built around Ethena USDe/sUSDe vaults. Merchants manage deployments, branding and domains in Business UI; customers use a deployment's public site to connect a wallet and access the vault.

• Business UI — sign in and open Deployments → Yield (/deployments/yield); create a deployment or open one to edit branding, manage Domains and inspect Contracts.
• Business UI guide — setup and navigation; find the customer site's hostname on the deployment.
• Merchant OpenAPI (JSON) — yield-deployment configuration routes, authenticated with a merchant JWT.

The server supplies this orientation during MCP initialization. It currently has no yield-deployment tools; use Business UI for management. The bundled skill's /stablecoinx floysh command provides the navigation guide.

Tools (37)

| Group | Tools | |---|---| | Auth & onboarding | auth_status, auth_send_otp, auth_verify_otp, auth_logout, api_key_create, session_key_create | | Merchant profile | merchant_get, merchant_update | | API keys | api_keys_list, api_keys_revoke | | Sessions | sessions_list, sessions_get, sessions_create_dashboard, sessions_create_s2s | | Paymaster clients (mode live/test, gasMode) | paymaster_clients_list, paymaster_clients_create, paymaster_clients_update, paymaster_clients_revoke | | Paymaster allowlist | paymaster_allowlist_list, paymaster_allowlist_add, paymaster_allowlist_remove | | Paymaster deny rules | paymaster_deny_rules_list, paymaster_deny_rules_add, paymaster_deny_rules_remove | | Paymaster spend limits | paymaster_limits_get, paymaster_limits_update | | Paymaster activity | paymaster_activity_list, paymaster_overview_get, paymaster_recent_ops | | Paymaster usage & billing | paymaster_usage_get, paymaster_balance_get | | Webhooks | webhooks_create, webhooks_list, webhooks_delete, webhooks_rotate_secret, webhooks_deliveries | | Batch execution | tools_batch |

Use tools_batch for several calls with known arguments. Consecutive reads run in parallel (up to four); writes execute one at a time in input order. The first error stops new calls and returns completed results, errors and skipped steps. Already-started reads finish. Batches contain up to 20 calls and share the same validation, auth checks and secret filtering as ordinary tools.

{
  "calls": [
    { "id": "clients", "tool": "paymaster_clients_list" },
    { "id": "allowlist", "tool": "paymaster_allowlist_list" },
    { "id": "balance", "tool": "paymaster_balance_get" }
  ]
}

Check each result status before continuing. Batches do not retry or roll back writes. Batch ordering, error contract and examples.

First-time auth

In your MCP client:

> Run auth_send_otp with my email [email protected]
> Verify with code 123456
> Show me my merchant profile

auth_send_otp emails a 6-digit code; auth_verify_otp derives the in-app smart account, signs the SIWE login payload, and caches a 24h JWT in the encrypted local state file. After 24h, re-run auth_send_otp / auth_verify_otp.

For server-to-server endpoints (sessions_create_s2s), run api_key_create once to mint and cache an sk_* (no expiry). For future on-chain operations, run session_key_create to provision a local EOA session key (30-day window).

Bundled skill

skills/stablecoinx/ is a bundled skill that generates checkout integration code (session creation, payment redirect, webhook handler with HMAC-SHA256 verification) and drives merchant onboarding / verification through this MCP. setup installs it to ~/.claude/skills/stablecoinx. Invoke it as /stablecoinx or just ask to integrate StablecoinX payments. It works with or without the MCP connected; the MCP provides merchant management and monitoring tools.

Gas sponsorship integration is covered by the paymaster guide. For transfers from an existing MetaMask Smart Account, use the Advanced Permissions guide: a bounded wallet permission, a separate session smart account and the SCX paymaster plus bundler. Check the deployed paymaster reference linked there for supported networks and permission constraints.

An installed skill is a local copy and does not update when the MCP package updates. Refresh it with npx -y @stablecoinx/mcp@latest setup --skill-only, then start a new client session. --skill-only updates the bundled skill without changing MCP registration or its state passphrase.

Configuration

| Env var | Required | Notes | |---|---|---| | SCX_STATE_PASSPHRASE | yes | You choose any string; derives the aes-256-gcm key for the local state file. | | SCX_STATE_DIR | no | %APPDATA%\stablecoinx-mcp (Windows) / $XDG_CONFIG_HOME/stablecoinx-mcp. |

The harness API URL, the publishable thirdweb client ID, the request Origin (business.harness.stablecoinx.com), and the login chain are baked into the package — none are configurable. The client ID + origin let a headless Node process pass thirdweb's Allowed Domains check (Node fetch sends no Origin by default; an undici interceptor injects it).

What's stored on disk

<SCX_STATE_DIR>/state.enc - encrypted JSON envelope with up to three slots:

• jwt: bearer token + expiry (24h TTL)
• apiKey: raw sk_* (set by api_key_create)
• sessionKey: local EOA private key + smart-account address + permission window

Encryption: aes-256-gcm, key via scrypt(SCX_STATE_PASSPHRASE, randomSalt), file mode 0o600, atomic writes. Anyone with both the state file and the passphrase can act as the merchant - keep the passphrase out of shell history and chat transcripts.

Update / uninstall

npx always resolves the latest published version, so there is nothing to update manually. To remove:

claude mcp remove stablecoinx-mcp
rm -rf "$SCX_STATE_DIR"            # or %APPDATA%\stablecoinx-mcp on Windows

Server-side credentials remain until revoked from the dashboard (API keys) or via removeSessionKey() from an admin signer (session keys).

Privacy

All authentication and state stay on the local machine. The only outbound calls are to the StablecoinX API (Authorization: Bearer ...) and thirdweb endpoints (OTP / RPC / bundler). No telemetry; nothing is uploaded.

Known limitations

• JWT refresh requires re-OTP every 24h. With the default thirdweb Account contract, a scoped session key can't sign the SIWE refresh (ERC-1271 approvedTargets check inside isValidSignature).
• Single merchant per state dir. Use a distinct SCX_STATE_DIR per merchant.