get_messages
List all SMS messages received in this session without consuming the OTP.
Use this to inspect raw messages or check if an SMS arrived before calling wait_for_otp. Does NOT mark the OTP as consumed.
LABSCO SUMMARY
The SMS step that usually stops an agent, handled inside the same conversation.
The blocking wait is the design that makes it usable — the agent asks for the code and gets it, instead of polling and reasoning about whether the message has landed. Sessions hold real allocations, so releasing them matters, and list_numbers exists precisely to find the ones a failed run left behind.
What it is
An MCP server for AgentSIM. It gives an agent a programmable phone number to receive SMS one-time codes, blocks until the code arrives, and returns it — so a signup or login flow that needs a text message can be finished without a human holding a handset.
What you get
- provision_number — lease a temporary number for receiving SMS OTP codes, returning the number in E.164 form and the session id every later call needs
- wait_for_otp — block until an SMS code arrives for the session, polling up to a timeout you set, and return the code with the message it came from
- get_messages — list every SMS received on the session without consuming the code, for inspecting the raw text or confirming one arrived
- release_number — return the allocation to the pool; worth calling even on the error path so capacity is not held
- list_numbers — the active sessions on the account, optionally by agent, to find leaked ones
Requirements
An AgentSIM API key in AGENTSIM_API_KEY, from console.agentsim.dev. Clients run uvx agentsim-mcp over stdio, or connect to the hosted server at https://mcp.agentsim.dev/mcp over Streamable HTTP with the key in an x-api-key header. Numbers are US only.
Setup effort
One command plus a key — uvx agentsim-mcp, then supply credentials
USE CASES
01
Completing a signup that texts a code
Lease a number, use it in the form, wait for the code and release the number afterwards.
02
Testing an SMS flow you built
Read the raw messages that arrived without consuming the code, to check the wording and timing.
03
Cleaning up after a failed run
List the active sessions on the account and release the ones nothing is using.
5 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
list_numbers
List active sessions, optionally filtered by agent_id.
Use this to check for leaked sessions or inspect what numbers are currently active in your account.
provision_number
Lease a temporary programmable phone number for receiving SMS OTP codes.
Returns the phone number (e164 format) and a session_id needed for all subsequent calls. The number is reserved for your session for ttl_seconds.
Next step: use the returned number on your target service to trigger an SMS, then call wait_for_otp with the returned session_id.
release_number
Release a provisioned number back to the pool.
Always call this when you are done with the session — even on error — to avoid consuming pool capacity unnecessarily.
wait_for_otp
Block until an SMS OTP arrives for this session, then return the code.
Polls the AgentSIM API for up to timeout_seconds. Returns the OTP code and the message it was extracted from.
If the OTP does not arrive in time, raises a ToolError with advice on retrying. Always call release_number after you have used the OTP.
BEFORE YOU INSTALL
What to know first
Tools you get
5 tools when we connected; the project documents 7. The two missing are the primary tools, open_challenge and wait_for_verdict; provision_number and wait_for_otp are backward-compatibility aliases for them. open_challenge also covers email OTP, magic links and WebAuthn, not just SMS.
Requires
- uvx on PATH
- AGENTSIM_API_KEY in your environment
Where it runs
Both documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
uvx
TERMINAL
uvx agentsim-mcpHosted endpoint
ENDPOINT URL
https://mcp.agentsim.dev/mcpAdd this hosted endpoint to your MCP client using the credentials listed under Requirements.
MCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add agentsim -e AGENTSIM_API_KEY=<YOUR_AGENTSIM_API_KEY> -- uvx agentsim-mcpClaude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"agentsim": {
"command": "uvx",
"args": [
"agentsim-mcp"
],
"env": {
"AGENTSIM_API_KEY": "<YOUR_AGENTSIM_API_KEY>"
}
}
}
}
