@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.

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 20+. 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.

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 [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 only accelerates auth/key/webhook operations.

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.