SMS8 MCP API documentation
JSON-RPC 2.0 over HTTPS. Seven tools. Bearer authentication. Works with Claude Code, Cursor, Windsurf, Codex and any MCP-compatible AI tool.
One HTTPS endpoint, JSON-RPC 2.0
All calls go to https://mcp.sms8.io. GET serves the landing. POST runs the protocol.
- Protocol: Model Context Protocol revision 2024-11-05
- Methods:
initialize,tools/list,tools/call,ping - Transport: HTTP (or stdio via
@sms8/mcp) - Content type:
application/json - Auth:
Authorization: Bearer YOUR_KEY
curl https://mcp.sms8.io \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk_…" \ -d '{"jsonrpc":"2.0","id":1, "method":"tools/list"}'
Seven tools, full schemas
Each description matches what your AI assistant sees in tools/list.
setup_sms8
Public. Validates the API key, returns account info, devices, and next-steps. Call once per session.
Args: api_key (optional, header preferred)
send_sms
Send one SMS through a paired Android. Per-device and per-SIM routing.
Args: phone, message, device_id, sim_slot, devices, option, random_device
send_otp
Generate and dispatch a verification code. Stores hash + expiry server-side.
Args: phone, length (4-8), template, expires_in (60-900), max_attempts (1-10)
verify_otp
Constant-time compare against the latest OTP for that phone. Returns verified + attempts_left on mismatch.
Args: phone, code
get_messages
Fetch recent inbox or sent SMS. Bound SQL parameters.
Args: direction (all|received|sent), limit (1-100), phone
list_devices
Return every paired Android device with enabled flag, primary flag, and model.
Args: none
create_webhook
Register a callback URL for inbound SMS + delivery events. SSRF-guarded. HMAC-signed.
Args: url (HTTPS), enabled (default true)
Error codes
-32601 method not found · -32602 invalid params · -32001 missing api_key · -32002 invalid api_key · -32603 internal · -32700 parse error
Bearer header, three accepted patterns
Authorization header is preferred. Other paths exist for backward compatibility.
Authorization: Bearer
Header-based. Key stays out of URLs, browser history, and server access logs.
Authorization: Bearer sk_…
X-Api-Key header
Alternative header for tools that cannot set Authorization.
X-Api-Key: sk_…
POST body field
OTP endpoints accept api_key= in the form body. POST only — GET returns 405.
api_key=sk_…
Working calls you can paste in
Send an SMS
curl https://mcp.sms8.io \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_SMS8_API_KEY" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"send_sms", "arguments":{"phone":"+1234567890", "message":"Hello from SMS8"}}}'
Issue and verify an OTP
curl https://mcp.sms8.io \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_SMS8_API_KEY" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call", "params":{"name":"send_otp", "arguments":{"phone":"+1234567890"}}}' curl https://mcp.sms8.io \ -H "Authorization: Bearer YOUR_SMS8_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call", "params":{"name":"verify_otp", "arguments":{"phone":"+1234567890","code":"123456"}}}'
List devices
curl https://mcp.sms8.io \ -H "Authorization: Bearer YOUR_SMS8_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":4,"method":"tools/call", "params":{"name":"list_devices","arguments":{}}}'
What the server enforces
Bound SQL parameters
Every query uses prepared statements. No user-input string interpolation.
SSRF block list
create_webhook blocks RFC1918, CGNAT, link-local, IPv4-mapped IPv6 and resolves the host at validation time.
Constant-time compare
verify_otp uses hash_equals for code matching. No byte-by-byte timing leaks.
Race-proof rate limits
OTP send and verify both wrap check + update in DB transactions with row locks.
API key redaction
setup_sms8 returns only the last 4 chars so the full key never lands in AI chat history.
CORS off for tools/call
Only discovery methods advertise CORS. Malicious web pages cannot drive SMS sends.
API questions
What protocol does the SMS8 MCP server use?
JSON-RPC 2.0 over HTTPS at mcp.sms8.io. The server implements MCP revision 2024-11-05 with initialize, tools/list, tools/call and ping methods.
How do I authenticate?
Send your SMS8 API key in the Authorization: Bearer header on every tools/call request. The X-Api-Key header is also accepted. The setup_sms8 tool is public; all other tools require authentication.
What are the rate limits?
SMS sending inherits from your SMS8 plan. OTP endpoints add a hard cap of 5 OTPs per phone per 24-hour window, a configurable resend cooldown (30 to 600 seconds, default 60), and a per-OTP attempt cap (default 5).
Is A2P 10DLC required?
No. SMS8 routes messages through your paired Android phone and SIM, so A2P 10DLC registration is not required. No carrier fees, no phone-number provisioning, no per-message charges.
Does the server log my API key?
No. The setup_sms8 response masks the key to last 4 chars. OTP endpoints accept POST only and ignore cookies. Use the Bearer header rather than putting the key in URL query strings.