@cmdoss/suipay-mcp

SuiPay MCP lets an MCP-capable agent pay MPP-gated HTTP resources from a buyer-funded Sui allowance. Buyer owns escrow. Local delegate can spend only to bound recipient, under on-chain per-payment cap.

Install

Pin package version in MCP config:

claude mcp add --scope user suipay -- npx -y @cmdoss/[email protected]

No wallet secret belongs in this command or MCP config.

First connection

1. Ask agent to call suipay_login.
2. Browser opens SuiPay console.
3. Connect buyer wallet, choose funding and per-payment cap, then approve allowance creation.
4. Local MCP process saves delegate credentials to ~/.suipay/credentials.json with mode 0600.
5. Agent can call pay in same MCP session.

Delegate private key is generated locally. It never enters browser URL, browser page, SuiPay backend, logs, or callback payload. Only delegate public key and address leave local process. Platform sponsors create and pay gas through backend Enoki key. Owner and delegate need no SUI gas.

Tools

| Tool | Purpose | | --- | --- | | discover | Search live managed-gateway resources | | pay | Fetch resource, settle MPP challenge from allowance, present finalized proof | | receipts | List settlement receipts, optionally by challenge ID | | suipay_login | Open browser allowance provisioning flow | | suipay_logout | Remove local credentials, guarded while live escrow still holds funds |

All tools remain visible before login. pay and receipts return instruction to run suipay_login when no credentials exist.

Client environment

SUIPAY_GATEWAY_URL=https://gateway.example
SUIPAY_CONSOLE_URL=https://console.example
SUIPAY_RPC_URL=https://your-testnet-rpc.example
SUIPAY_NETWORK=testnet

Optional:

# Defaults to $SUIPAY_GATEWAY_URL/api/sponsor
SUIPAY_SPONSOR_URL=https://gateway.example/api/sponsor

# Fallback payment terms when suipay_login receives no gatewayResourceUrl
SUIPAY_PACKAGE_ID=0x...
SUIPAY_RECIPIENT=0x...
SUIPAY_COIN_TYPE=0x...::usdc::USDC

SUIPAY_MIN_FUNDED=5000000
SUIPAY_MIN_MAX_PER_PAYMENT=5000000
SUIPAY_LABEL="My agent"

ENOKI_PRIVATE_API_KEY is backend-only. Never set it in MCP config or local SuiPay credentials.

If SUI_SECRET_KEY is present, it must derive to delegate address stored in credentials. Mismatch or malformed credentials stop signing. No mnemonic or ephemeral payment fallback exists.

Logout safety

suipay_logout refuses to delete local key while live allowance still holds funds. Revoke and refund allowance in console first. force=true removes local credentials but does not recover escrow.

Build and run locally

pnpm --filter @cmdoss/suipay-mcp build
node packages/mcp/dist/bin/suipay.js

Binary writes status banner to stderr only. Stdout stays reserved for MCP protocol.

Testnet E2E

See root .env.testnet.example, start backend with Enoki sponsorship, then run:

SUIPAY_E2E_CONFIRM=1 pnpm tsx scripts/e2e-mcp-testnet.ts

Script uses real testnet assets. Default funding equals one payment so successful run leaves escrow balance at zero. It verifies delegate SUI balance stays zero before and after pay.