What happens if nobody answers in time?

The question expires and wait_for_answer reports it as expired. An expired or cancelled question means no decision was made, so your agent should treat it as "do not proceed", never as approval.

Which API key do I need?

An account API key (iop_live_...) from Dashboard → Settings → API keys, with the push:send, questions:ask and questions:read scopes, which are the defaults. A per-topic key is send-only and cannot ask questions.

How long can an agent wait for an answer?

A question stays answerable for timeout_s seconds (10 to 86400, default 300). Each wait_for_answer call blocks for up to 55 seconds, so an agent calls it again while the question is still pending.

Does it work on the free plan?

Yes. The Free plan includes 100 pushes and 20 approvals a month. Quorum approvals (several people must approve) and answer delegation are on the Team plan.

API docs / MCP server

iotPush MCP server

Let an AI agent reach you on your phone. It can send you a notification, or ask a question and wait for your answer before it does something you would want to sign off on: a deploy, a refund, a destructive command.

Endpoint

https://mcp.iotpush.com/mcp

Transport is Streamable HTTP (POST /mcp). SSE is not supported. You need an account API key (iop_live_...) from Dashboard → Settings → API keys, and the iotPush app on your phone to receive the questions.

Connect your client

Claude Code

Terminal

claude mcp add --transport http iotpush https://mcp.iotpush.com/mcp \
  --header "Authorization: Bearer iop_live_..."

Cursor, and clients with remote HTTP support

~/.cursor/mcp.json (or your client's MCP config)

{
  "mcpServers": {
    "iotpush": {
      "url": "https://mcp.iotpush.com/mcp",
      "headers": { "Authorization": "Bearer iop_live_..." }
    }
  }
}

Clients that only speak stdio

MCP config

{
  "mcpServers": {
    "iotpush": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.iotpush.com/mcp",
               "--header", "Authorization:Bearer iop_live_..."]
    }
  }
}

Clients that support MCP OAuth

Add the URL on its own. Your client opens a page where you paste your API key once, and optionally pick a default topic. The key is checked before it is stored.

Tools

Tool	What it does
`send_notification`	Send a push to a topic. Fire-and-forget: a build broke, a long task finished.
`ask_user`	Ask a question as confirm (Approve/Reject), select (2–4 choices) or input (free-text reply). Returns a question_id straight away.
`wait_for_answer`	Block until the question is answered or the wait elapses. Up to 55 seconds per call; call again while it is pending.
`cancel_question`	Withdraw a question you no longer need answered.
`list_topics`	List the topic names this connection can use, and whether the plan supports two-way questions.
`send_pushover_notification`	Send using Pushover's message fields, for agents already written against Pushover.

How ask and wait works

The agent calls ask_user. The question arrives on your phone with its buttons.
The agent calls wait_for_answer, which returns when you answer or after up to 55 seconds.
While the question is still pending, the agent calls it again, until you answer or the question's timeout_s runs out.

No answer means no. An expired or cancelled question is not an approval. The tool says so in its description, and your agent's instructions should too.

Options on ask_user include reminders (remind_every_s), idempotency_key so a retry doesn't ask twice, and on the Team plan quorum, where several people must approve and any one reject vetoes.

The same flow is available without MCP: POST /api/v1/questions, then GET /api/v1/questions/{id}/wait?timeout=30. Runnable curl, Python and Node versions are in the iotpush-examples repo.

Errors your agent can act on

Failures come back as codes with a plain explanation, not bare HTTP statuses.

`two_way_required`	The plan doesn't include approvals; send_notification still works.
`no_reachable_device`	No phone could receive the question, so waiting would never finish.
`topic_not_found`	Call list_topics for valid names.
`insufficient_scope`	The API key is missing a scope; the error says which.

Questions

What happens if nobody answers in time?: The question expires and wait_for_answer reports it as expired. An expired or cancelled question means no decision was made, so your agent should treat it as "do not proceed", never as approval.
Which API key do I need?: An account API key (iop_live_...) from Dashboard → Settings → API keys, with the push:send, questions:ask and questions:read scopes, which are the defaults. A per-topic key is send-only and cannot ask questions.
How long can an agent wait for an answer?: A question stays answerable for timeout_s seconds (10 to 86400, default 300). Each wait_for_answer call blocks for up to 55 seconds, so an agent calls it again while the question is still pending.
Does it work on the free plan?: Yes. The Free plan includes 100 pushes and 20 approvals a month. Quorum approvals (several people must approve) and answer delegation are on the Team plan.

Plans and limits are on the pricing page. For plain HTTP sends, see the API docs.