Let your agent report and ask.

01Before you start

Start with an account and a conversation in the Pushyou mobile app. Web sign-in requires QR approval in that app. The setup guide lets you choose a conversation and verify delivery.

For OAuth, choose the conversations and permissions during the approval flow; no separate API key is needed. Program keys are an alternative configured in Settings → Connections. Creating a new conversation requires all-room access and conversations:write.

02Authentication

The server uses Streamable HTTP. With OAuth, your client opens an approval flow; approve the requested conversations and permissions in Pushyou. With a program key, the same scope checks apply. Keep OAuth and Bearer-key configurations separate.

https://pushyou.app/mcp

Add the server entry to ~/.codex/config.toml and run codex mcp login pushyou. Remove any existing Bearer key configuration for Pushyou to use OAuth. You can also use the MCP authentication control in the app or IDE.

[mcp_servers.pushyou]
url = "https://pushyou.app/mcp"

03Verify with a real exchange

Start with pushyou_get_account, then pushyou_list_conversations. Confirm the account, permissions and target room before sending. Replace YOUR_CONVERSATION_ID below. These are MCP tool arguments, not REST request bodies.

{}

{
  "limit": 20
}

{
  "conversation_id": "YOUR_CONVERSATION_ID",
  "id": "docs-mcp-message-01",
  "text": "Pushyou connection verified.",
  "notify": true
}

Reply to the message in Pushyou, then call pushyou_get_events once. Inspect events and next_cursor. A successful tool call does not prove the device received a push notification, and connecting MCP does not keep an agent running in the background.

{
  "conversation_id": "YOUR_CONVERSATION_ID",
  "after": 0
}

MCP list tools use limit (1–50, default 20) and before. Event tools use after. List messages summarize cards; pushyou_get_message returns full content. Use pushyou_get_media for original photos or byte ranges of larger files.

04Questions & decisions

Call pushyou_ask when a choice, an approval or missing input is the owner’s to decide. It sends the question once, notifies the owner and waits up to wait_seconds (default 45) for the answer. If it returns waiting, call it again with the same arguments; the question is not sent twice. pushyou_get_answer checks an earlier question by its ID. Answers go to the asking agent, not to receivers.

{
  "conversation_id": "YOUR_CONVERSATION_ID",
  "id": "docs-mcp-question-01",
  "question": "Refactor finished and **all tests pass**. Deploy to staging?",
  "options": [
    {
      "id": "deploy",
      "label": "Deploy"
    },
    {
      "id": "wait",
      "label": "Not yet"
    }
  ]
}

For consequential work that another program executes, request a task instead of asking. Give repeated task types a stable kind, such as deploy-staging. After several approvals of the same kind, the owner can turn on a standing rule for that conversation in the mobile app: matching tasks are then created already queued, within a daily limit, and the owner can turn the rule off from the app or web. Check the returned status rather than assuming a review.

Use priority: low for routine progress. Those messages skip the immediate notification and are counted in the owner’s daily summary, together with tasks approved by a standing rule. Questions and approval requests notify right away.

Instructions for your agent

Add a short section like this to the project’s CLAUDE.md or AGENTS.md so the agent reports and asks through Pushyou. Replace the conversation ID with your own.

## Pushyou
- Report meaningful results to the Pushyou conversation `YOUR_CONVERSATION_ID` with `pushyou_send_message`. Lead with the outcome; Markdown is rendered. Use `priority: "low"` for routine progress.
- When a decision is mine (approval, a choice between options, missing information), call `pushyou_ask` in that conversation with one clear question and short options, then continue with the answer. If it returns `waiting`, call it again with the same arguments. Do not guess on decisions that affect external systems.
- Never put credentials, tokens or private keys in messages.

05Replies & execution

Reply in the app, then fetch events. After actually handling an ordinary reply or action, save the result, send its ACK, and persist next_cursor. ACK does not remove an event or claim exclusive execution. Use one ordinary responder per room, or coordinate consumers yourself.

Tasks track approval and execution together. After the owner approves, a worker reads events with task_protocol=1, persists its execution token, claims the attempt, and keeps the claim alive with heartbeats. It saves the actual result before complete. Task completion also acknowledges the event; a standalone ACK cannot finish a pending task.

Webhooks

Signed outbound webhooks are also supported. Configure them in the mobile app’s Response webhooks settings. Verify the original body signature and deduplicate delivery IDs. HTTP 2xx confirms receipt, not task completion. The downloadable workflow guide includes the signature and retry contract.

06Files & views

MCP uses pushyou_prepare_media_upload. Supply media_id, filename, content_type, byte size and SHA-256. POST the original bytes to the returned upload.url with its exact file-specific headers within five minutes, then send attachment_ids. The same preparation is available through REST. Do not substitute an account key or MCP OAuth token for the upload grant.

Use pushyou_set_view with a report, actions or html card to publish an optional conversation view. Set view to null to remove it. The view opens from its owning conversation. HTML cannot access external networks, app credentials or browser storage; declared actions return events to the same room.

Card =
  { type: "report", title: string, items: { title: string, body?: string, label?: string }[] }
| { type: "actions", title: string, body?: string, actions: { id: ID, label: string }[] }
| { type: "html", title: string, html: string, height?: integer, actions?: { id: ID, label: string }[] }

Field = { id: ID, label: string, type: "text" | "multiline" | "number" | "date" | "select" | "checkbox", required?: boolean, options?: string[], min?: number, max?: number }

07Tool reference

The server supports these tools. Your authenticated tools/list response includes only tools allowed by your connection, with their current input schemas. Room scope is checked again on every call.

08Troubleshooting

REST failures return a non-2xx status and {"error": "…"}. MCP tool failures are reported by the client; check the structured error and whether the connection still has permission.