@stablecoinx/mcp

@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.
• Public StablecoinX harness (Base / Arbitrum / Ethereum Sepolia testnets), reachable without VPN.

Quick start

npx @stablecoinx/mcp setup

This installs the stablecoinx skill into ~/.claude/skills and registers the MCP (claude mcp add, user scope) with the harness defaults and a freshly generated state passphrase. 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_API_URL=https://api.harness.stablecoinx.com \
  -e SCX_CHAIN_ID=84532 \
  -e THIRDWEB_CLIENT_ID=830ece55cd210c34f351166a85edbd0f \
  -e THIRDWEB_ORIGIN=https://business.harness.stablecoinx.com \
  -e SCX_STATE_PASSPHRASE="$(openssl rand -hex 16)" \
  -- npx -y @stablecoinx/mcp

Requires Node.js 20+. 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. THIRDWEB_CLIENT_ID is a public, publishable identifier - not a secret.

Supported networks

The harness runs on three testnets - pick one via SCX_CHAIN_ID:

Network	SCX_CHAIN_ID
Base Sepolia (default)	84532
Arbitrum Sepolia	421614
Ethereum Sepolia	11155111

Tools (27)

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	paymaster_clients_list, paymaster_clients_create, paymaster_clients_update, paymaster_clients_revoke
Paymaster allowlist	paymaster_allowlist_list, paymaster_allowlist_add, paymaster_allowlist_remove
Paymaster usage	paymaster_usage_get
Webhooks	webhooks_create, webhooks_list, webhooks_delete, webhooks_rotate_secret, webhooks_deliveries

First-time auth

In your MCP client:

> Run auth_send_otp with my email [e-mail]
> 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 only accelerates auth/key/webhook operations.

Configuration

Env var	Required	Default (harness)
SCX_API_URL	yes	https://api.harness.stablecoinx.com
SCX_CHAIN_ID	yes	84532 (see Supported networks)
THIRDWEB_CLIENT_ID	yes	830ece55cd210c34f351166a85edbd0f (publishable)
THIRDWEB_ORIGIN	yes	https://business.harness.stablecoinx.com
SCX_STATE_PASSPHRASE	yes	you choose; derives the aes-256-gcm key for the local state file
SCX_STATE_DIR	no	%APPDATA%\stablecoinx-mcp (Windows) / $XDG_CONFIG_HOME/stablecoinx-mcp

THIRDWEB_CLIENT_ID together with THIRDWEB_ORIGIN lets 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.