Tools Reference

All tools are authenticated with your AGENTSIM_API_KEY. Sessions created via MCP appear in your console like any other challenge session. We run the auth challenge so your agent doesn’t die there — on apps you own. Google and Stripe stay refused.

Primary tools

`open_challenge`

Opens an auth challenge session. Same REST call as the SDK’s openChallenge() / open_challenge: POST /v1/sessions.

Parameter	Type	Default	Description
`agent_id`	string	required	Identifies the requesting agent
`channel`	string	`"sms_otp"`	`sms_otp` requires live access. Email and magic-link channels accept injected test messages only. `webauthn_required` stops the run
`service_url`	string	required	Public HTTPS origin of the owned target, verified before allocation
`country`	string	`"US"`	ISO country code (`sms_otp` only)
`ttl_seconds`	number	`3600`	Session lifetime in seconds (60–86400)
`webhook_url`	string	—	URL to POST the verdict to (optional)

Returns: session_id, channel, agent_id, expires_at, number (sms_otp), inbox_address (email_otp / magic_link), next_step The TypeScript SDK exports openChallenge() (provision is an alias). Python exports open_challenge (provision is an alias). MCP uses open_challenge.

`wait_for_verdict`

Blocks until a verdict is ready or the timeout expires. Same REST call as waitForVerdict() / wait_for_verdict: POST /v1/sessions/:id/wait. Timeouts are seconds.

Parameter	Type	Default	Description
`session_id`	string	required	Session ID from `open_challenge`
`timeout_seconds`	number	`60`	Max wait time in seconds (1–120)

Returns: session_id, received_at, plus any of otp_code, magic_link, webauthn_required, verdict, next_step

If wait_for_verdict times out, treat it as delivery evidence. Inspect message records, then retry or close the challenge. A successful live number assignment or extension uses one session from your live allowance, even if no code arrives. Failed assignments use none.

The TypeScript SDK exports waitForVerdict() (waitForOtp is an alias). Python exports wait_for_verdict (wait_for_otp is an alias).

Aliases (still supported)

These names stay for existing MCP callers. New integrations should use open_challenge and wait_for_verdict.

`provision_number`

Alias for open_challenge with channel=sms_otp.

Parameter	Type	Default	Description
`agent_id`	string	required	Identifies the requesting agent
`service_url`	string	required	Public HTTPS origin of your app
`country`	string	`"US"`	Currently `US`
`ttl_seconds`	number	`3600`	Session lifetime in seconds (60–86400)
`webhook_url`	string	—	URL to POST the verdict to (optional)

Returns: session_id, number (E.164), expires_at, next_step

`wait_for_otp`

Alias for wait_for_verdict (SMS). Also supports auto_reroute on timeout.

Parameter	Type	Default	Description
`session_id`	string	required	Session ID from `open_challenge` or `provision_number`
`timeout_seconds`	number	`60`	Max wait time in seconds
`auto_reroute`	boolean	`true`	On timeout, request a session extension; the number may stay the same and an extension can use allowance

Returns: otp_code, from_number, received_at, next_step on success. With automatic renewal after timeout, returns status: "carrier_retry_required", session_id, new_number, previous_number, country, expires_at, and message. This status does not establish a carrier fault.

`get_messages`

Returns message metadata and parsed codes, without raw SMS bodies. Reading a parsed OTP marks it consumed; a later wait will not return that code.

Parameter	Type	Default	Description
`session_id`	string	required	Session to query

Returns: { messages, has_more }

`release_number`

Closes the challenge session.

Parameter	Type	Default	Description
`session_id`	string	required	Session to close

Returns: { status: "completed" }

`list_numbers`

Lists unexpired active challenge sessions for the account associated with your API key. API failures are reported as errors, rather than an empty list.

Parameter	Type	Default	Description
`agent_id`	string	—	Filter results by agent ID (optional)
`limit`	integer	100	Maximum results per page (1–100)
`after`	string	—	Last `session_id` from the previous page

Returns: { sessions: [{ session_id, number, agent_id, expires_at, ... }], has_more }. When has_more is true, call again with the last session_id as after.

Testing with curl

Testing with curl (raw HTTP)

MCP clients (Claude Desktop, Claude Code, Cursor) handle the protocol automatically. The hosted endpoint uses stateless HTTP, so direct curl requests do not need an initialize handshake or an mcp-session-id header.AgentSIM challenge session_id values are separate from MCP transport sessions. Pass the challenge ID returned by open_challenge to later tool calls.

Every curl request must include Accept: application/json, text/event-stream. Omitting this header returns a 406 “Not Acceptable” error.

Set AGENTSIM_API_KEY first and replace the example target with a real public HTTPS origin you own. Live calls require account access. Define this helper once in your shell. It sends a complete MCP request and extracts the JSON payload from the event stream:

mcp_request() {
  curl -sS -X POST https://mcp.agentsim.dev/mcp \
    -H "x-api-key: $AGENTSIM_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    --data "$1" \
    | sed -n 's/^data: //p'
}

List available tools:

mcp_request '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq '.result.tools[].name'

Open a challenge:

mcp_request '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"open_challenge","arguments":{"input":{"agent_id":"curl-test","service_url":"https://staging.example.com","channel":"sms_otp"}}}}' \
  | jq .

Wait for the verdict (10s timeout):

# Replace SESSION_ID with the session_id from open_challenge
mcp_request '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"wait_for_verdict","arguments":{"input":{"session_id":"SESSION_ID","timeout_seconds":10}}}}' \
  | jq .

Close the session:

mcp_request '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"release_number","arguments":{"input":{"session_id":"SESSION_ID"}}}}' \
  | jq .

Tool arguments are wrapped in an input key: "arguments": {"input": { ...params... }}. Omitting the input wrapper will return a validation error.

Get Started

Guides

Integrations

API Reference

SDKs

MCP

Resources

Primary tools

`open_challenge`

`wait_for_verdict`

Aliases (still supported)

`provision_number`

`wait_for_otp`

`get_messages`

`release_number`

`list_numbers`

Testing with curl

​Primary tools

​open_challenge

​wait_for_verdict

​Aliases (still supported)

​provision_number

​wait_for_otp

​get_messages

​release_number

​list_numbers

​Testing with curl

Primary tools

`open_challenge`

`wait_for_verdict`

Aliases (still supported)

`provision_number`

`wait_for_otp`

`get_messages`

`release_number`

`list_numbers`

Testing with curl