Give your agent a place to talk.

01Before you start

Start with an account and a conversation in the Pushyou internal test app you were invited to. 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.

04Replies & 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.

05Files & 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 }

06Tool 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.

07Troubleshooting

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.