Deja que tu agente informe y pregunte.

01Antes de empezar

Crea una cuenta y una conversación en la aplicación móvil de Pushyou. El acceso web requiere aprobar un QR en esa app. La guía de conexión permite elegir la conversación y comprobar la entrega.

Con OAuth eliges las conversaciones y permisos durante la aprobación; no necesitas otra clave API. Las claves de programa son una alternativa en Ajustes → Conexiones. Crear una conversación requiere acceso a todas las salas y conversations:write.

02Autenticación

El servidor usa Streamable HTTP. Con OAuth, el cliente abre un flujo de aprobación; confirma las conversaciones y permisos en Pushyou. Una clave de programa aplica los mismos controles. Mantén separadas las configuraciones OAuth y Bearer.

https://pushyou.app/mcp

Añade el servidor a ~/.codex/config.toml y ejecuta codex mcp login pushyou. Elimina la configuración Bearer existente para usar OAuth. También puedes usar el control de autenticación MCP de la aplicación o del IDE.

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

03Comprueba un intercambio real

Empieza por pushyou_get_account y pushyou_list_conversations. Confirma la cuenta, los permisos y la sala antes de enviar. Sustituye YOUR_CONVERSATION_ID. Los ejemplos son argumentos de herramientas MCP, no cuerpos REST.

{}

{
  "limit": 20
}

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

Responde en Pushyou y llama una vez a pushyou_get_events. Revisa events y next_cursor. Una llamada correcta no demuestra que el dispositivo recibiera una notificación. Conectar MCP tampoco mantiene al agente activo en segundo plano.

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

Las listas MCP usan limit (1–50, 20 por defecto) y before. Los eventos usan after. Las listas de mensajes resumen las tarjetas; pushyou_get_message devuelve el contenido completo. Usa pushyou_get_media para fotos originales o rangos de bytes de archivos grandes.

04Preguntas y decisiones

Llama a pushyou_ask cuando una elección, una aprobación o un dato que falta dependa del propietario. Envía la pregunta una sola vez, avisa al propietario y espera la respuesta hasta wait_seconds (45 por defecto). Si devuelve waiting, vuelve a llamarla con los mismos argumentos; la pregunta no se envía dos veces. pushyou_get_answer consulta una pregunta anterior por su ID. Las respuestas llegan al agente que preguntó, no a los receptores.

{
  "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"
    }
  ]
}

Para trabajo importante que ejecuta otro programa, solicita una tarea en lugar de preguntar. Da a los tipos de tarea repetidos un kind estable, como deploy-staging. Tras varias aprobaciones del mismo kind, el propietario puede activar una regla permanente para esa conversación en la app móvil: las tareas que coinciden se crean ya en cola, dentro de un límite diario, y el propietario puede desactivar la regla desde la app o la web. Comprueba el estado devuelto en lugar de suponer una revisión.

Usa priority: low para el progreso rutinario. Esos mensajes no generan una notificación inmediata y se cuentan en el resumen diario del propietario, junto con las tareas aprobadas por una regla permanente. Las preguntas y las solicitudes de aprobación avisan al momento.

Instrucciones para tu agente

Añade una sección breve como esta al CLAUDE.md o AGENTS.md del proyecto para que el agente informe y pregunte a través de Pushyou. Sustituye el ID de la conversación por el tuyo.

## 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.

05Respuestas y ejecución

Responde en la app y consulta los eventos. Tras procesar realmente una respuesta o acción ordinaria, guarda el resultado, envía su ACK y conserva next_cursor en almacenamiento persistente. El ACK no elimina el evento ni concede ejecución exclusiva. Usa un único programa de respuesta por sala o coordina los consumidores.

Las tareas reúnen aprobación y resultado. Tras la aprobación del propietario, un proceso consulta eventos con task_protocol=1, guarda su token de ejecución y reclama el intento. Mantiene la concesión con heartbeat y guarda el resultado real antes de complete. Completar también confirma el evento; un ACK independiente no termina una tarea pendiente.

Webhooks

También hay webhooks de respuesta firmados. Configúralos en los ajustes de Webhooks de respuesta de la app móvil. Verifica la firma del cuerpo original y evita duplicados por ID de entrega. HTTP 2xx confirma recepción, no finalización de la tarea. La guía de flujos detalla firmas y reintentos.

06Archivos y vistas

En MCP, llama a pushyou_prepare_media_upload con media_id, filename, content_type, tamaño en bytes y SHA-256. Envía los bytes originales mediante POST a upload.url, con los encabezados específicos devueltos, en cinco minutos. Después envía attachment_ids. REST ofrece la misma preparación. No sustituyas la autorización de carga por una clave de cuenta o token OAuth MCP.

Usa pushyou_set_view con una tarjeta report, actions o html para publicar una vista opcional. Envía view como null para retirarla. Se abre desde su conversación. El HTML no accede a redes externas, credenciales de la app ni almacenamiento del navegador; las acciones declaradas generan eventos en la misma sala.

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 }

07Referencia de herramientas

Estas son las herramientas del servidor. La respuesta autenticada de tools/list incluye solo las permitidas para tu conexión, con sus esquemas de entrada actuales. Se comprueba el acceso a la sala en cada llamada.

08Solución de problemas

Los errores REST devuelven un estado distinto de 2xx y {"error": "…"}. El cliente muestra los errores MCP; revisa el error estructurado y los permisos de la conexión.