x402-sms-mcp

x402-sms-mcp

A paid MCP server that lets AI agents send SMS messages to US phone numbers.

Each send_sms tool call:

1. Sends a transactional SMS via a verified toll-free number
2. Auto-appends Reply STOP to opt out if the body doesn't include opt-out language
3. Costs $0.03 USDC per message, paid automatically from the configured wallet via x402

No API keys. No Twilio account. The agent pays the toll, the message goes out.

Status (2026-05-22): Public beta on Base Sepolia (testnet). The seller's toll-free number is undergoing Twilio TFV approval (submitted 2026-05-14, still in queue). During this window /send calls short-circuit to a 503 delivery_pending_tfv_approval response before the buyer wallet signs anything, so no USDC is moved. The day Twilio approves the number, delivery flips on; pricing flips to Base mainnet shortly after.

Install in Claude Desktop / Cursor / Windsurf

Add this to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "x402-sms": {
      "command": "npx",
      "args": ["-y", "x402-sms-mcp"],
      "env": {
        "BUYER_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY"
      }
    }
  }
}

Restart your MCP client. A send_sms tool will appear.

What you need

A wallet on Base Sepolia (testnet) funded with:

• A small amount of ETH for gas (free from <https://www.coinbase.com/faucets/base-ethereum-sepolia-faucet>)
• USDC for payments (free from <https://faucet.circle.com>, select Base Sepolia)

Generate a throwaway key:

node -e "const {generatePrivateKey,privateKeyToAccount}=require('viem/accounts');const k=generatePrivateKey();console.log('PRIVATE_KEY=',k);console.log('ADDRESS=',privateKeyToAccount(k).address)"

Use the printed address to claim from faucets, then put the printed key into your MCP config.

Try it

In Claude Desktop, ask:

Text my cell at +15551234567 when this long-running task finishes. The recipient (me) consents to receive this message.

Claude will call send_sms with opt_in_attestation: true. You'll get back a Twilio SID + the on-chain settlement hash. The transfer is visible at <https://sepolia.basescan.org>.

Compliance — please read

This MCP wraps a regulated SMS gateway. The operator (you) is responsible for ensuring every recipient has consented to receive messages before invoking send_sms. The opt_in_attestation: true argument is your legal attestation under TCPA and CTIA short-code/long-code rules.

Do NOT use this MCP to:

• Send marketing or promotional content
• Text strangers, scraped lists, or anyone who hasn't opted in
• Send to non-US numbers (the seller currently rejects non-+1 E.164)
• Send anything related to S.H.A.F.T.-C (Sex, Hate, Alcohol, Firearms, Tobacco, Cannabis)

The seller-side automatically:

• Appends Reply STOP to opt out to every message
• Honors carrier-level STOP/HELP keyword handling
• Logs each send for audit purposes

If you have any doubt about consent, do not call this tool.

Configuration

| Env var | Required | Default | | ------------------- | -------- | -------------------------------------------------------------------- | | BUYER_PRIVATE_KEY | yes | — | | SMS_URL | no | https://x402-sms-server-production.up.railway.app/send |

To point the MCP server at your own seller deployment, override SMS_URL.

Errors you might see

The MCP surfaces three distinct error shapes so the model can explain what happened to the user and decide whether to retry.

| Cause | What you'll see in chat | Was payment taken? | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | :----------------: | | Seller's toll-free number still in TFV review (HTTP 503) | "SMS not sent — service is in pre-launch wait" + the seller's submitted date and retry guidance | no | | Buyer wallet exceeded per-minute/hour/day rate limit (HTTP 429) | "SMS not sent — this buyer wallet hit the per-X rate limit" + retry_after_seconds | no | | Twilio-side rejection (e.g. invalid number 21211, opted-out 21610) | Friendly hint mapped from the Twilio error code + the full response body | yes (the send tried) |

For the full mapping of Twilio error codes the MCP recognizes, see TWILIO_HINTS in src/index.ts.

How it works

Claude Desktop ──tool call──> MCP server (this package, on your machine)
                              │
                              │ x402 payment (USDC, Base Sepolia)
                              │ + to/message/opt_in_attestation
                              ▼
                              Public seller (Hono + Twilio on Railway)
                              │
                              │ Twilio dispatch
                              ▼
                              SMS lands on recipient's phone
                              │
                              │ Twilio SID + status
                              ▼
                              MCP server ──tool result──> Claude Desktop

The MCP server doesn't talk to Twilio directly. It signs an x402 payment with the buyer's wallet, sends the payment + message details to the seller endpoint, and the seller's verified toll-free number dispatches the SMS. Your private key never leaves your machine. The seller never sees it.

Roadmap

• Now (2026-05-22): Base Sepolia testnet, TFV pending. Payment flow verified end-to-end; deliveries gated on Twilio approval.
• Once TFV clears: Real US SMS delivery, testnet pricing held while we collect early traffic.
• A few weeks out: A2P 10DLC Brand approval → higher per-day throughput tier.
• Mainnet flip: Production launch, USDC settles on Base mainnet; Solana facilitator on roadmap after.

License

MIT