@yukwaindustries/spheavy-mcp

MCP server for SP-Heavy — lets an AI coding agent make real sandbox payments and audit the webhook endpoint it just wrote.

An agent can write a payment integration that looks correct and has never been run. These tools close that gap: it can drive a success, drive each failure, post a signed webhook at its own handler, and be told when that handler accepts a forged signature.

Sandbox only. Every tool refuses pk_live_/sk_live_ keys unless SPHEAVY_ALLOW_LIVE=true is set deliberately. An agent should not be able to move real money because a .env had the wrong keys in it.

Install

Claude Code

claude mcp add spheavy -- npx -y @yukwaindustries/spheavy-mcp

Then set the keys in ~/.claude.json under that server's env, or export them before launching.

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json in the project):

{
  "mcpServers": {
    "spheavy": {
      "command": "npx",
      "args": ["-y", "@yukwaindustries/spheavy-mcp"],
      "env": {
        "SPHEAVY_PUBLIC_KEY": "pk_test_…",
        "SPHEAVY_SECRET_KEY": "sk_test_…",
        "SPHEAVY_WEBHOOK_SECRET": "whsec_…"
      }
    }
  }
}

Claude Desktop

Same block, in claude_desktop_config.json.

Get sandbox keys at spheavy.com → API Keys → Generate key (leave the toggle on Sandbox). The webhook secret is under Account.

Configuration

| Variable | Required | Purpose | | --- | --- | --- | | SPHEAVY_PUBLIC_KEY | yes | pk_test_… | | SPHEAVY_SECRET_KEY | yes | sk_test_… | | SPHEAVY_WEBHOOK_SECRET | for webhook tools | whsec_…, signs the test events | | SPHEAVY_BASE_URL | no | Defaults to https://api.spheavy.com | | SPHEAVY_ALLOW_LIVE | no | true permits live keys. Do not set this casually. |

Tools

| Tool | What it does | | --- | --- | | create_test_collection | Makes a real sandbox charge. The last four digits of the phone number choose the outcome, so failures can be driven deliberately. | | check_transaction_status | Authoritative status, optionally polling the operator directly. | | list_transactions | Recent transactions for the key. | | get_balance | Wallet balances, per currency and environment. | | simulate_webhook | POSTs a correctly signed event to a local URL, so a handler can be driven without waiting for a payment. | | verify_my_webhook_endpoint | Audits an endpoint: valid event, forged signature, wrong secret, replayed delivery, duplicate id — and reports what each returned. |

Sandbox outcomes

The last four digits of the phone number decide what happens:

| Number | Outcome | | --- | --- | | 237670000000 (or any other) | SUCCESSFUL | | 237670000001 | FAILED — NOT_ENOUGH_FUNDS | | 237670000002 | FAILED — APPROVAL_REJECTED | | 237670000003 | FAILED — EXPIRED | | 237670000004 | FAILED — PAYER_NOT_FOUND | | 237670000009 | PENDING forever |

Typical use

Add SP-Heavy checkout to this app, then use the spheavy tools to prove it works: take a test payment, make it fail with insufficient funds, and audit my webhook route.

verify_my_webhook_endpoint is the one that matters. An endpoint that accepts a forged signature will pass every test an agent writes for itself, because the agent generates the signature it also verifies. This posts a signature it does not control.

One thing it cannot check from outside: whether a duplicated event was fulfilled once or twice. It reports the X-SPHeavy-Id it reused so you can check your own records.

Rules the agent should be following

See AGENTS.md, or https://spheavy.com/llms-full.txt for the complete reference with runnable code.

License

MIT © Yukwa Industries