Key Takeaways
- wait_for_otp is an agent flow around send + verify — not a busy-loop that hammers GET /messages.
- Failure modes: infinite poll, premature resend, treating stream idle as delivery fail.
- Use deadlines, backoff, and human entry. DLR/webhooks beat sleeping the model.
- MCP remains a REST wrapper. The Android radio still owns last-mile latency.
- Airtime is yours. Free/Developer pause when the platform SMS allowance is exhausted.
MCP Server for Android SMS Gateway: wait-for-OTP agent flow — failure modes covers the orchestration that sits between send_otp and verify_otp. Send & verify tools · Webhook via MCP. Spec: MCP. DLR: Delivery reports.
Devices and send volume. You fund the SIM.
A deadline beats an infinite spinner. Resend is a product decision, not a reflex.
Wait is orchestration, not sleep-on-radio
The agent may wait for user paste, a webhook, or a status tool. It must not invent delivery by polling every 200 ms until prepaid dies.
“Wait forever then resend” is how users get three codes and support gets three tickets. Cap the wait; name the exit.
Wait-for-OTP failure table
| Failure | Cause | Safe response |
|---|---|---|
| Poll storm | Tight GET loop | Backoff + max attempts |
| Triple SMS | Resend on every timeout | One cooldown; same key if uncertain |
| Host session ends | Streamable HTTP idle | Resume flow; stream failures |
| User never gets SMS | Doze / airtime | Phone ops — not another tool call |
| Cap mid-flow | Allowance exhausted | Fail closed; On Free and Developer, sending pauses when you use the plan SMS allowance rather than silently billing aggregator-style overage. Upgrade or request a custom allowance to continue. |
Poll storms and prepaid burn
Status checks are cheap at the platform; the failure is the agent deciding each “still pending” means send again. Separate observe from mutate.
Timeout vs resend
Uncertain timeout → check id. Terminal fail or product cooldown → optional resend with a new challenge. Error classes.
Prefer webhook or user entry
Webhook message.delivered / message.failed or the user typing the code beats sleeping the model on RF latency. OTP use case.
Next steps
Instrument a 90-second deadline with one allowed resend in staging. Install the app. Free is 300 SMS lifetime — spend it on flow tests, not poll storms.
Related product pages
Jump to the live product docs for this topic—not another long-form article.
- OTP and 2FA SMS on AndroidAuthentication flows
- SMS API documentationLive endpoint reference
- device and SMS volume pricingPlans and allowances
- Android SMS gateway product guideDefinition, product, and how to buy
