에이전트와 대화할 공간을 연결하세요.

01시작하기 전에

초대받은 Pushyou 내부 테스트 앱에서 계정과 대화방을 먼저 만드세요. 웹 로그인은 해당 앱의 QR 승인이 필요합니다. 연결 설정에서는 대화방을 선택하고 실제 전송을 확인할 수 있습니다.

OAuth는 승인 과정에서 대화방과 권한을 선택하며 별도 API 키가 필요하지 않습니다. 프로그램 키는 설정 → 연결 관리에서 만드는 다른 인증 방법입니다. 새 대화방을 생성하려면 모든 대화방 범위와 conversations:write가 필요합니다.

02인증

Streamable HTTP 서버입니다. OAuth를 선택하면 클라이언트가 승인 흐름을 엽니다. Pushyou에서 요청된 대화방과 권한을 확인하고 승인하세요. 프로그램 키에도 같은 범위 검사가 적용됩니다. OAuth 설정에 Bearer 키 설정을 섞지 마세요.

https://pushyou.app/mcp

기존 ~/.codex/config.toml에 서버 항목을 추가하고 codex mcp login pushyou를 실행하세요. 기존 Pushyou 항목의 Bearer 키 설정은 제거해야 로그인 방식으로 연결됩니다. 앱·IDE의 MCP 인증 버튼도 사용할 수 있어요.

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

03실제 메시지와 답장으로 확인

pushyou_get_account와 pushyou_list_conversations부터 호출하세요. 계정·권한·대상 방을 확인한 뒤 전송합니다. 아래 YOUR_CONVERSATION_ID를 실제 값으로 바꾸세요. 예시는 REST 본문이 아닌 MCP 도구 인자입니다.

{}

{
  "limit": 20
}

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

Pushyou에서 메시지에 답장한 뒤 pushyou_get_events를 한 번 호출해 events와 next_cursor를 확인하세요. 도구 호출 성공이 기기 푸시 수신까지 증명하지는 않습니다. MCP 연결만으로 에이전트가 백그라운드에서 상시 실행되지도 않습니다.

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

MCP 목록 도구는 limit(1–50, 기본 20)과 before를, 이벤트는 after를 사용합니다. 메시지 목록에는 카드 요약이 포함되고 pushyou_get_message로 전체 내용을 읽습니다. 사진 원본이나 큰 파일의 바이트 구간은 pushyou_get_media를 사용하세요.

04답장 수신과 업무 실행

앱에서 답장한 뒤 이벤트를 조회하세요. 일반 답장·액션의 실제 처리를 마친 후 결과 저장 → ACK → next_cursor 영구 저장 순서로 진행합니다. ACK는 이벤트 삭제나 독점 실행 권한이 아닙니다. 일반 자동 응답은 방마다 한 프로그램을 사용하거나 별도로 조정하세요.

업무는 승인과 실행 결과를 함께 추적합니다. 소유자가 승인하면 작업 프로그램이 task_protocol=1로 이벤트를 조회하고 실행 토큰을 영구 저장한 뒤 해당 시도를 선점합니다. heartbeat로 점유를 유지하고 실제 결과를 저장한 후 complete를 보냅니다. 완료 시 이벤트도 ACK됩니다. 별도 ACK로 미완료 업무를 끝낼 수 없습니다.

Webhooks

서명된 응답 Webhook도 지원합니다. 모바일 설정의 응답 Webhook에서 연결하세요. 원본 본문의 서명을 검증하고 전달 ID로 중복을 막아야 합니다. HTTP 2xx는 수신 확인이며 업무 완료가 아닙니다. 서명과 재시도 규칙은 업무 가이드에서 확인할 수 있습니다.

05파일과 대화방 화면

MCP에서는 pushyou_prepare_media_upload에 media_id, filename, content_type, 바이트 크기, SHA-256을 보냅니다. 반환된 upload.url과 파일 전용 헤더 그대로 5분 안에 원본 바이트를 POST한 뒤 attachment_ids로 전송하세요. REST에서도 같은 준비 API를 제공합니다. 업로드 권한을 계정 키나 MCP OAuth 토큰으로 바꾸면 안 됩니다.

pushyou_set_view에 report, actions, html 카드를 전달해 선택적인 대화방 화면을 게시하고 view를 null로 보내 제거합니다. 화면은 해당 대화방에서 엽니다. HTML은 외부 네트워크·앱 자격 증명·브라우저 저장소에 접근할 수 없으며 선언한 액션은 같은 방의 이벤트로 전달됩니다.

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 }

06도구 레퍼런스

서버가 지원하는 도구 목록입니다. 인증된 tools/list 응답에는 연결 권한으로 허용된 도구와 최신 입력 스키마만 포함됩니다. 호출할 때마다 대화방 범위를 다시 검사합니다.

07문제 해결

REST 오류는 2xx가 아닌 상태와 {"error": "…"}를 반환합니다. MCP 도구 오류는 클라이언트에 표시됩니다. 구조화된 오류와 연결 권한을 함께 확인하세요.