# OnExit: agent integration reference OnExit lets agents reach a person with a notification or alarm on one linked phone. A handoff is a message with a scheduled delivery time, short label, and optional longer message. The web dashboard manages phones, keys, history, and account settings. Native apps receive handoffs and schedule alarms locally. ## Set up 1. The person signs up, installs a native app, and links a phone. 2. In Agents on the web dashboard, they create a connection for that phone and choose Message (notify) or Alarm delivery. 3. Choose the MCP client and use Copy setup prompt. Paste it into the agent to configure the local client. For manual hosted MCP setup, use `https://api.onexit.app/mcp` with `Authorization: Bearer ` and `X-OnExit-Timezone: `. Do not put the key in a URL, source repository, prompt log, or public page. 4. Run ping, list_devices, and get_current_time before the first send. Confirm the returned phone, delivery mode, and timezone. Ask before sending a test. The CLI command is `onexit`; the hosted MCP endpoint is the installation-free path. CLI/MCP builds are available from the source repository for beta testers; do not assume a public npm package exists. A locally linked CLI uses `onexit mcp` for stdio MCP. `onexit login --api-url ` signs in and stores a session/key locally. OAuth supports --google or --apple when enabled on the server. ## MCP tools - ping: read-only connection, credential, target phone, and delivery-mode check. - get_current_time: current UTC and configured timezone. - send_handoff: fireAt, label; optional message, recurrence, critical, metadata. - list_handoffs: scheduled and recent handoffs visible to this key. - list_devices: the pinned phone for a normal key; no push tokens. - cancel_handoff: cancel a scheduled handoff by id. - ack_handoff: acknowledge a fired handoff after the person confirms it was handled. fireAt accepts relative text such as "in 10 seconds", "tomorrow 7am", or an ISO timestamp. The X-OnExit-Timezone header sets the hosted MCP timezone. ONEXIT_TZ sets the source-built stdio MCP/CLI timezone. Both fall back to UTC. Check the returned absolute fireAt and fireAtLocal. Avoid computing dates from an assumed model clock. label: 1–200 characters. message: 1–2000 characters. metadata: a JSON object of at most 4096 serialized UTF-8 bytes, for agent retrieval; it is not notification content. recurrence: daily, weekly, or weekdays. Critical requests must have the user's permission and cannot guarantee bypassing silent mode or DND. ## CLI onexit ping onexit test --in 10s onexit send "in 10 seconds" "Review the fix" --message "Tests pass. The pull request is ready for your review." onexit list --json onexit cancel onexit ack `onexit keys` and `onexit devices` use a human session. Agent tools cannot create keys, change billing, or enroll phones. Run `onexit --help` for current options. ## REST Use Authorization: Bearer and Content-Type: application/json. - GET /health: public liveness only. - GET /config: public product/auth configuration, never credentials. - GET /v1/devices: permitted phone descriptors. - GET /v1/alarms: handoffs visible to the key. - POST /v1/alarms: {"fireAt":"","label":"Preview ready","message":"Open the preview to check the updated form."} - DELETE /v1/alarms/{id}: cancel. - POST /v1/alarms/{id}/ack: acknowledge. REST requires an ISO fireAt; natural language is resolved by MCP/CLI. IDs are UUIDs. The key's device and mode control the destination and delivery; do not try to override these in a payload. ## Failures and retries 401: credentials are missing, expired, or revoked; ask the user to reconnect. 403: missing scope or forbidden operation; do not seek broader access automatically. 404: the record is unavailable to this credential, including a foreign record. 409: the handoff state may have changed; read the current state before acting again. 429: rate or monthly usage limit; inspect the message and avoid retry loops. Plan usage is per person, not per phone. 5xx/network timeout: read-only calls may be retried with bounded backoff. A timed-out create may already have succeeded. List recent handoffs before creating another; there is no general idempotency-key guarantee. ## Delivery truth Acceptance, delivery to the phone, and acknowledgement are distinct states. New handoffs require connectivity and phone permissions. Only an alarm already armed locally can ring offline. Notification mode does not promise a ringing alarm. Never claim the person saw a message solely because send_handoff succeeded. ## More [Human guide](/docs/), [Plans](/#pricing), [Privacy](/privacy/), [Terms](/terms/), [Contact](/contact/). ## Writing useful updates Use a short title for the result or blocker and a message with context and the next action. Examples: “Review the fix” (tests pass; review the PR), “Access needed” (return to the agent thread to grant a permission), “Scan still running” (state what completed and what remains), and “Check the rollout” (a scheduled alarm after a canary window). Delivery mode belongs to the key. Do not imply that a message was read, that a reply is supported in the phone app, or that incomplete work is finished. ## Prompt-based setup In the web app, link a phone, open Agents, choose the phone and delivery mode, and create a connection. Choose Cursor, Codex, or another MCP client, then use Copy setup prompt. The generated prompt includes the correct hosted endpoint, a unique server name, the device ID, timezone, and a private bearer key. It is available only in the current page session; do not log, commit, or repeat its key. Merge the configuration into the user's local MCP settings. Cursor uses ~/.cursor/mcp.json with mcpServers, url, and headers. Codex uses ~/.codex/config.toml with mcp_servers, url, and http_headers. The hosted server needs no package install or repository checkout. Restart or reconnect the client if required; report unfinished steps accurately. Verify using ping, list_devices, and get_current_time. Confirm the phone and key delivery mode. Ask before sending a test handoff. API acceptance does not prove phone receipt. If the key is lost, create a replacement connection and revoke the old one after updating the client. A copied prompt is not proof of an active MCP connection. The CLI is currently source-built for beta testers, not a public npm install.