# x402-sms **Category:** πŸ’° Finance & Fintech **Repository:** https://github.com/UltraStarz/x402-sms-mcp **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/x402-sms ## Description Pay-per-call MCP server. $0.03 USDC sends one transactional SMS to a US phone number via x402. ## Claude Desktop Quick Installation Heuristic fallback β€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "x402-sms": { "command": "npx", "args": ["-y","x402-sms"] } } ``` ## Documentation & README # 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](https://x402.org) 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): ```json { "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 ) - USDC for payments (free from , select Base Sepolia) Generate a throwaway key: ```bash 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 . ## 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