agentsim-mcp

MCP server that exposes AgentSIM challenge tools to AI coding assistants: Claude Code, Cursor, Windsurf, and any other MCP-compatible host. Primary tools: open_challenge, wait_for_verdict. Aliases: provision_number, wait_for_otp.

Setup

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
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, webauthn_required, or policy_denied
get_messages	List raw SMS messages received on a session
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	Long-poll until an OTP arrives — kept for backward compatibility

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 (more coming soon)