Skip to main content
The hosted MCP server uses HTTP transport (streamable-HTTP). Every request must include your API key in an x-api-key header. An env entry only supplies credentials to a local server process.
Get a key from Keys in the console, then choose your client below. The free plan includes 10 live US SMS sessions per month; check Availability for limits and number setup. Keep configurations containing a real key out of source control.

​
Codex CLI

Add this table to ~/.codex/config.toml. If an agentsim table already exists, update it instead of adding a duplicate:
In a macOS or Linux terminal using Bash or Zsh, run the following command, paste your API key when it waits, and press Enter. The key is hidden while you type and is not included in the command history:
Then launch Codex from that same terminal:
The environment variable supplies the hosted x-api-key header. The 150-second tool limit leaves time for a 120-second SMS wait. This setup is for Codex CLI; an already-running desktop app does not automatically receive this terminal’s environment. See Codex MCP configuration for other setup options.

​
Give Codex browser access

AgentSIM receives the SMS. Codex also needs a browser tool to enter the phone number and submit the code on your app. If it already has browser access, keep that setup. Otherwise, install the Playwright MCP server using its documented prerequisites, then add it:
Restart Codex after changing MCP configuration. Keep normal tool approvals enabled. If your app presents a CAPTCHA, ask a person to complete it while keeping the browser and current AgentSIM session open. Continue the same pending request afterward. Release the session if the person is unavailable or the handoff times out. First verify the AgentSIM connection, then use the complete sign-in prompt. An app you own must be ready to send real SMS; connecting MCP alone does not send a code.

​
Claude Desktop

Install uv so uvx is available. In Claude Desktop, open Settings → Developer → Edit Config and add the local AgentSIM server:
Replace asm_live_... with your API key. On macOS, this configuration is at ~/Library/Application Support/Claude/claude_desktop_config.json. Restart Claude Desktop after saving.

​
Claude Code

​
Cursor

Add to ~/.cursor/mcp.json for your own use, or .cursor/mcp.json for a project:
Reload the Cursor window after saving (Command Palette, then “Reload Window”).

​
Other MCP clients

Any MCP-compatible client that supports HTTP transport can connect using the same configuration shape:
If your client uses a different config format, supply:
  • Transport: HTTP (streamable-HTTP)
  • URL: https://mcp.agentsim.dev/mcp
  • Request header: x-api-key: YOUR_API_KEY
The hosted endpoint is stateless and does not issue an mcp-session-id header. The session_id returned by AgentSIM tools identifies your challenge across tool calls.

​
Verify your connection

Once connected, open a new chat and ask:
“List my active AgentSIM challenge sessions.”
The assistant should call list_numbers and return your active sessions, or confirm that there are none. This checks the connection without opening a live session. If the tools are missing, check the configuration path and restart your client. If the server returns 401, check that your key is active and that the hosted configuration sends the x-api-key header. When you’re ready for real SMS, check your remaining free allowance. No card is required. Use open_challenge with the public HTTPS service_url of an app you own. Have that app send the code to the returned number, then call wait_for_verdict. Submit the received code in your app and confirm that sign-in succeeded before calling release_number. Always release the session on failure too. Each successful number assignment or extension uses one session from your live allowance; the console demonstration remains free.