About Agentsim
Agentsim is an MCP server for AI coding assistants to run authentication challenges using real SIM-backed US phone numbers. It supports SMS OTP and other challenge channels, with tools to open sessions, wait for verdicts, read messages, and release sessions.
Key features
- 01Open authentication challenge sessions
- 02Wait for structured challenge verdicts
- 03Read SMS metadata and parsed codes
- 04Release sessions and list active sessions
- 05Support SMS, email, magic link, and WebAuthn channels
Use cases
- 01Complete phone-based sign-in challenges
- 02Wait for an OTP or magic link
- 03Inspect incoming SMS verification codes
- 04Release a number after a challenge
MCP support
Provides challenge tools to MCP hosts through local stdio setup or a hosted Streamable HTTP endpoint. MCP clients can open challenges, wait for verdicts, read messages, and manage sessions.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
https://mcp.agentsim.dev/mcpclaude mcp add --transport http agentsim https://mcp.agentsim.dev/mcp{"mcpServers":{"agentsim":{"type":"http","url":"https://mcp.agentsim.dev/mcp"}}}Open in Cursor{"servers":{"agentsim":{"type":"http","url":"https://mcp.agentsim.dev/mcp"}}}Open in VS Code{"mcpServers":{"agentsim":{"type":"http","url":"https://mcp.agentsim.dev/mcp"}}}{"mcpServers":{"agentsim":{"serverUrl":"https://mcp.agentsim.dev/mcp"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
Tools
5| Parameter | Type | Required | Description |
|---|---|---|---|
| input | object | Yes | |
| input.agent_id | string | Yes | Unique identifier for the agent requesting the number (e.g. 'checkout-bot'). |
| input.country | string | No | ISO 3166-1 alpha-2 country code. Supported: US. More countries coming soon. |
| input.ttl_seconds | integer | No | How long to hold the number (seconds). Default 1 hour. |
| input.webhook_url | any | No | Optional HTTPS URL to receive OTP via webhook instead of polling. |
Details
From the project READMEagentsim-mcp
Availability: Live SMS is self-serve for owned public HTTPS services after exact-origin verification and an allow policy. Hobby includes 10 live US SMS sessions per UTC month, with one active live session per account and no card required. Builder is $99/month and includes 50 live US SMS sessions. Checkout shows tax and renewal terms before payment, and existing agreements keep their terms. Check current access and channel support before using live examples.
MCP server that exposes AgentSIM challenge tools to AI coding assistants: Codex CLI, Claude Code, Cursor, Windsurf, and any other MCP-compatible host. Primary tools: open_challenge, wait_for_verdict. Aliases: provision_number, wait_for_otp.
Setup
For Codex CLI, follow Connect Codex. It covers key handling, the SMS wait timeout, and browser access. Then use the complete phone sign-in prompt.
Claude Code
claude mcp add agentsim -e AGENTSIM_API_KEY=asm_live_xxx -- uvx agentsim-mcp
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"agentsim": {
"command": "uvx",
"args": ["agentsim-mcp"],
"env": {
"AGENTSIM_API_KEY": "asm_live_xxx"
}
}
}
}
Cursor / Windsurf
Add agentsim-mcp as a stdio MCP server with AGENTSIM_API_KEY in the environment config.
Remote (no install)
Connect directly to the hosted MCP server without installing anything locally:
{
"mcpServers": {
"agentsim": {
"type": "streamable-http",
"url": "https://mcp.agentsim.dev/mcp",
"headers": {
"x-api-key": "asm_live_..."
}
}
}
}
The hosted endpoint uses stateless HTTP and does not issue mcp-session-id headers. The session_id returned by AgentSIM tools identifies a challenge and remains valid across tool calls.
Tools
Control-Plane Nouns (Recommended)
| Tool | Description |
|---|---|
identify_agent | Add a stable agent ID to the console without opening a challenge, sending SMS, or using allowance |
open_challenge | Open an authentication challenge session for a required owned service_url; accepts channel (sms_otp | email_otp | magic_link | webauthn_required), returns session ID + identifier |
wait_for_verdict | Long-poll for the challenge verdict — returns structured outcome including otp_code, magic_link, or webauthn_required; policy denial fails on open |
get_messages | Read SMS metadata and parsed codes; reading codes consumes them |
release_number | Release a session early (allocation returned to pool) |
list_numbers | List all active sessions for this account |
Legacy Aliases (Backward Compatibility)
| Tool | Maps to | Description |
|---|---|---|
provision_number | open_challenge(channel=sms_otp) | Provision a temporary programmable US number for SMS OTP — kept for backward compatibility |
wait_for_otp | wait_for_verdict | Legacy wait with automatic extension after timeout by default; number may be unchanged |
Auth
For stdio, set AGENTSIM_API_KEY in the process environment. For hosted HTTP, every request must send its own x-api-key; the server validates and forwards that caller-scoped key. Get a key at console.agentsim.dev.
Supported Countries
US
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.