DOCUMENTATION

Connect an agent to one phone.

Link your phone and copy a setup prompt. Your agent handles the MCP configuration.

01 — START HERE

Link a phone first.

01
Sign in to the web app.
Create your OnExit account, then open Phones.
02
Link the phone you want an agent to reach.
Use the QR flow or sign in on the iOS or Android app.
03
Create a connection.
Open Agents, choose your phone and Message or Alarm, then select Connect agent.
04
Copy the setup prompt.
Choose Cursor, Codex, or another MCP client. Copy the prompt and paste it into your agent. It configures the connection and checks the phone, mode, and timezone.

One prompt, one phone.

The prompt includes a private key, shown only when you create the connection. Share it only with your agent. The key can work with its linked phone; it cannot enroll phones, create keys, or change billing.

02 — MCP

Set up with a prompt.

The Copy setup prompt button in Agents prepares these settings for your chosen client. Paste it into your agent and let it configure MCP. If the client needs a restart, your agent will tell you. Setup uses read-only checks and asks before sending a test.

Configure MCP manually

The MCP server exposes a small set of tools: ping the API, get the current time, send a handoff, list handoffs and devices, cancel a handoff, and acknowledge one that arrived. Message or Alarm mode is fixed by the key. Tools: ping, get_current_time, send_handoff, list_handoffs, list_devices, cancel_handoff, ack_handoff. The hosted server runs at the URL below, so you do not need Node, Python, a local onexit binary, or a repository checkout.

For a bounded list, pass limit (1–100) and reuse the returned nextCursor as after with the same filters until it is empty. MCP returns { items, nextCursor } when paging options are set; calls without them keep the legacy list response.

Cursor · ~/.cursor/mcp.json

{
  "mcpServers": {
    "onexit-mcp": {
      "url": "https://api.onexit.app/mcp",
      "headers": {
        "Authorization": "Bearer aa_...",
        "X-OnExit-Timezone": "Asia/Kolkata"
      }
    }
  }
}

Use the generated configuration from Agents for your own URL, key, and timezone. Merge the server entry into your existing configuration; keep other servers in place. Each new connection has a unique server name.

Codex · ~/.codex/config.toml

[mcp_servers.onexit-mcp]
url = "https://api.onexit.app/mcp"
http_headers = { Authorization = "Bearer aa_...", "X-OnExit-Timezone" = "Asia/Kolkata" }

Reconnect the server, then call ping, list_devices, and get_current_time. Check the intended phone and delivery mode before sending. Configuration formats: Cursor MCP and Codex MCP.

Lost the prompt or key?

Keys cannot be retrieved after you leave or reload. Create a replacement connection, update your agent, then revoke the old one. Copying a prompt does not mean the agent is connected; its read-only checks confirm that.

03 — CLI

Send from the command line.

The CLI is currently available to beta testers building from the repository. It is not a public npm install. For setup without a checkout, use the hosted MCP prompt above. With the source-built CLI on your PATH, sign in and confirm the phone before sending.

terminal

onexit login --api-url https://api.onexit.app
onexit ping
onexit doctor
onexit devices
onexit send "in 10 seconds" "Review the fix" --message "Tests pass. The pull request is ready for your review."
onexit list

After a phone and a key.

MCP and CLI both send, list, cancel, and acknowledge handoffs, and both can ping the API. CLI also has test, plus session-only devices and keys. Rename, unlink, pairing, history, billing, and the account display name stay in the web console. An agent key cannot mint keys or change billing.

onexit list keeps its legacy output with no options. Add --limit, --after, and optional --status or --order to page through a large handoff list; continue with the returned cursor until there is no next page.

04 — REST API

Call it from a script.

Replace the example fireAt with a future ISO 8601 UTC time and use your own agent key. The key’s pinned device is selected for you, so an automated workflow cannot fan out to every phone on the account.

request

curl -X POST https://api.onexit.app/v1/alarms \
  -H "Authorization: Bearer aa_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fireAt": "REPLACE_WITH_FUTURE_ISO_UTC",
    "label": "Review the deploy",
    "message": "The canary has run for ten minutes. Check errors before expanding."
  }'

DELIVERY MODEL

How messages and alarms arrive.

Push tells the app there is a new handoff to fetch. Once an alarm has reached the phone, the operating system schedules it locally, so it can still ring after the network disappears. Use message mode for progress updates and review requests. Use alarm mode for a scheduled check or a task you need to act on promptly. You choose the mode when creating the agent key; the agent cannot change it.

EXAMPLES

Say what changed and what to do next.

Use a short title for the result or blocker. Put the context and next action in the message.

01
Review the fix · Message
Tests pass. The pull request is ready for your review.
02
Access needed · Message
Staging needs a database permission. Check the agent thread to continue.
03
Check the rollout · Alarm at 09:30
The canary has run for ten minutes. Check errors before expanding.
04
Scan still running · Message
The first batch is complete. Three matches found; the remaining batches are still running.

These are examples. An agent can report a result, ask you to return to its thread, or schedule a check. Set delivery mode on the agent key, and agree on which updates it should send.

PLANS AND BILLING

Plans and monthly usage.

Every plan includes the same handoff to your chosen phone and unlimited phones for your account. Billing is per person. A monthly allowance covers each message or alarm an agent creates; alarms you create yourself do not count, and there is no per-handoff charge.

01
Free · Try it with an agent
No card required.

$0 per month · 100 included handoffs per month
02
Pro · Daily agent updates
For daily updates from your agents.

$5 per month · 5,000 included handoffs per month
03
Ultra · More agents, more updates
For frequent updates from multiple agents.

$20 per month · 50,000 included handoffs per month

Manage billing on the web.

Open Plan & usage in the web app to change your plan, update your payment method, view invoices, or cancel. The phone apps show usage and link to the same page. If paid plans are unavailable, the web app shows a contact option.

Plans on the site Email us

Troubleshooting

Accepted is not the same as received.

Start with the MCP ping and list_devices tools. Ask your agent for a test only when you are ready to receive it. Check the key’s phone and delivery mode, connectivity, and notification permissions. An alarm can ring offline only after the phone has scheduled it locally.

A 401 means reconnect your key; 403 means the operation is not allowed; 429 means a rate or usage limit. After a network timeout, list recent handoffs before sending again—the first request may have succeeded.

In Activity, Provider accepted means the push service accepted a request. A separate phone report can show that a phone received, scheduled, or presented it. Provider acceptance does not confirm phone receipt, and a phone report does not confirm that you saw or heard it.

For agent-readable setup, tools, and failure handling, use llms.txt or the full agent reference.