verify402-mcp

verify402-mcp

MCP server for verify402: a free, fail-closed preflight gate before anagent signs a payment or a chain transaction, plus five paid on-chain checkspaid per call over x402.

Works with Claude Desktop, Cursor, OpenCode, and any MCP client that speaksstdio. The free gate needs no wallet. The paid tools use a dedicated hotwallet that pays in USDC; the bridge never signs or sends a trade.

Tools

preflight_gate is the front door. Call it before signing any cryptotransaction or x402 payment request. If sign_allowed is false, do notsign. If requires_ack is true, surface the reasons to the operator. Thereceipt expires (default 90s); call again instead of reusing it.

The gate is advisory at this layer: the bridge does not hold the agent'stransaction key and cannot stop an agent that ignores the answer. Enforcementbelongs in the executor that signs — verify the receipt, then sign. Seeexamples/preflight-guard.mjsfor a deny-by-default reference that refuses to call the signer without averified receipt.

Run

The package is distributed as a versioned GitHub release tarball. No npmaccount is required.

npx -y \
  --package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz \
  verify402-mcp --help

Warm the cache first. The first npx run installs the MCP SDK and viem;some clients kill a server that takes more than 30 seconds to start. Run the--help command once before adding it to an MCP client. After that, startup isfast.

From source:

git clone https://github.com/a32116150-ctrl/verify402
cd verify402/mcp-bridge
npm ci
node index.mjs --help

Free gate only (no key)

Omit EVM_PRIVATE_KEY. The server registers only preflight_gate and logsfree preflight_gate only. Nothing can be charged.

Paid tools (dedicated hot wallet)

Set a wallet with USDC on the payment network. Use a wallet with only the moneyyou are willing to spend — never a main wallet. The key stays in your MCP clientconfiguration or environment; the package never contains it.

EVM_PRIVATE_KEY=0x...        # optional; omit for free-only
VERIFY402_URL=https://verify402.onrender.com
MAX_PAYMENT_USD=0.25         # hard cap on ONE payment, enforced at signature time
MAX_DAILY_USD=0.50           # optional cap for the UTC day, persisted
SPEND_LEDGER_PATH=           # optional ledger path (default .spend-ledger.json)
VERIFY402_NETWORKS=eip155:8453   # paid calls only; comma-separated EVM networks
VERIFY402_PAY_TO=0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb
# VERIFY402_RESOURCE_PREFIX=https://verify402.onrender.com

The paid client refuses a 402 that names another network or payee, a resourceoutside the configured server, or a non-paid route. It also refuses redirects.The amount cap and the USDC-only default-asset allowlist are enforced insidethe x402 client, before a signature exists.

Claude Desktop / Cursor

claude_desktop_config.json, or .cursor/mcp.json:

{
  "mcpServers": {
    "verify402": {
      "command": "npx",
      "args": [
        "-y",
        "--package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz",
        "verify402-mcp"
      ],
      "env": {
        "VERIFY402_URL": "https://verify402.onrender.com"
      }
    }
  }
}

For paid tools, add "EVM_PRIVATE_KEY": "0x...", "MAX_PAYMENT_USD": "0.25"and optionally "MAX_DAILY_USD": "0.50" to env. The free gate works withoutthem.

OpenCode V2

opencode.jsonc, or the global ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "verify402": {
        "type": "local",
        "command": [
          "npx",
          "-y",
          "--package=https://github.com/a32116150-ctrl/verify402/releases/download/mcp-v1.0.2/verify402-mcp-1.0.2.tgz",
          "verify402-mcp"
        ],
        "environment": {
          "VERIFY402_URL": "https://verify402.onrender.com"
        }
      }
    }
  }
}

For paid tools, add "EVM_PRIVATE_KEY": "{env:EVM_PRIVATE_KEY}" toenvironment and export the key in the environment that starts OpenCode. Keepthe secret out of the config file.

Safety

• The bridge signs x402 payments only. It never signs or broadcasts a trade.
• Before signing, the paid client requires the 402 to come from the configuredserver and a known paid route, on an allowlisted EVM network, to theverify402 payee. It accepts only recognized default assets (USDC), caps theamount at MAX_PAYMENT_USD, and refuses redirects.
• The allowlist can be narrowed or pointed at another deployment withVERIFY402_NETWORKS, VERIFY402_PAY_TO, and VERIFY402_RESOURCE_PREFIX.Defaults are Base mainnet and the public verify402 payee.
• MAX_PAYMENT_USD is enforced inside the x402 client, before a signatureexists; removing it is a security regression.
• preflight_gate is a check, not a guarantee. Read notChecked: it does notscreen recipient reputation or sanctions, audit contracts, simulate fullbalance deltas, or protect against MEV. It catches the measurable signingmistakes, not every scam.
• Use the reference executorwhen you want enforcement rather than advice.

Development

npm pack --dry-run

License

Apache License 2.0. See LICENSE and NOTICE.

You may use, modify, and distribute this package, including in commercial agentsystems and bots. If you redistribute it or a product containing it, keep thecopyright notice, the license text, and the NOTICE file. The verify402 nameand logo are not licensed for endorsement.