Connect your agents.

In any client that supports remote MCP with OAuth, add https://ayy.fyi/mcp and follow its sign-in prompt. ayy runs in the cloud; there’s no local server to install.

If you previously added ayy with an agent key, remove that old connection and add it again using the command above.

If a previously connected agent can’t find the verification tool, refresh its MCP connection or restart the client to load the new tools.

Previously signed in with an email code? Use password reset to set a password for your existing account. Your conversations stay with you.

Manage access in your account or in the iPhone app’s Agents tab. Disconnecting an agent stops its access.

Tools for staying in the loop

• ayy_send_alert sends an update, question, or approval request. Include a stable idempotency_key to safely retry.
• ayy_get_response returns the conversation, replies, and approval decision. Follow the returned polling interval while waiting.
• ayy_acknowledge_response confirms the agent has read a reply or decision. Fetching a reply alone doesn’t confirm receipt.
• ayy_update_task reports running, waiting for input, completed, or failed independently of read and archive status.
• ayy_upload_attachment uploads a private screenshot, PDF, text document, or proposed diff for the next alert.
• ayy_verify_connection starts the real notification and reply check using the setup prompt from the iPhone app.
• ayy_reply adds context to an existing thread.
• ayy_list_alerts retrieves the agent’s recent conversations.

Projects bring related tasks together

Open the project picker above your iPhone inbox to create projects, rename them, or choose a color. Use a thread’s menu to move it to a project. All projects keeps everything together; No project shows threads you haven’t organized. Removing a project keeps its threads and messages.

Agents can call ayy_list_projects to find an existing project, or ayy_create_project with a name and optional color. Include repository_url for Git work: HTTPS and SSH remotes for the same repository reuse the same project, even if the agent supplies a different project name. Include its project_idwhen starting a task. Continue with the returned thread_idso updates follow the thread if you move it later.

ayy_create_project({
  name: "ayy",
  repository_url: "https://github.com/ahmad/ayy.fyi",
  color: "blue"
})

Send updates for this work to my ayy project, keeping each task in its own thread.

One thread per task

Give each focused task a stable, unique task_key and a short thread_title. Reuse the key, or the returned thread_id, for every related update, question, and approval. A single agent conversation can work on several tasks; each task gets its own thread in your inbox.

Use task keys such as ayy/fix-login to distinguish work across projects. Each alert still has its own id. Poll that alert ID when it needs a response. An earlier approval never approves a later request, even in the same thread.

How your reply reaches the agent

When an agent sends a question or approval request, ayy returns its id. The agent keeps that ID and calls ayy_get_response to check the conversation. Your iPhone replies are saved on the server and returned in messages, with sender: "user".

ayy_get_response({
    alert_id: "THE_ID_RETURNED_BY_AYY_SEND_ALERT"
  })

Begin checking immediately, then follow poll_after_seconds(normally 15 seconds) while should_poll is true. Checking opens replies for 90 seconds. Each check renews that window; if the agent stops, replies and decisions pause. Reading the inbox or listing alerts does not open the reply window.

Stop checking once a reply or decision arrives, the request expires, or should_poll becomes false. Updates always return false and never accept replies. A follow-up in a question or approval conversation begins another response turn, so the agent must start checking again. Send kind="update" in the same task thread for informational follow-ups.

A reply doesn’t wake a stopped agent. The app only accepts responses during an active polling window, and accepted responses stay saved even if the agent stops immediately afterward. The window is based on recent checks, not a guarantee that the agent process is still running. Notifications open the app so it can check current reply availability.

After reading a response, the agent calls ayy_acknowledge_responsewith the returned message IDs or exact decision. Your iPhone changes from “Reply saved” to “Agent received it.” Receipt confirms delivery, not that the task is finished. If the agent stops, use the thread’s resume prompt. A revoked connection needs a new connection and request.

Choices, forms, and previews

A question can include response_schema with up to five text, single-choice, or multiple-choice fields. Upload files with ayy_upload_attachment and pass the returned IDs as attachment_ids on an alert. Files stay private to the account and can be previewed or removed in the iPhone conversation. Each file can be up to 2 MB, with 100 MB of storage per account.

Report task_status on an alert or call ayy_update_taskwhen work changes. Catch up in the inbox shows recent completions and failures across projects, alongside running tasks and requests that need input.

Approvals mean something specific

An approval request is pending until you explicitly approve or decline it. A message, timeout, expired request, or missing response is never an approval. Your agent should perform only the action described in the approved request.

ayy_send_alert({
    task_key: "onboarding-redesign",
    thread_title: "Redesign onboarding",
    title: "Ready to ship?",
    body: "Open a pull request for the onboarding changes?",
    kind: "approval",
    idempotency_key: "onboarding-pr-v1"
  })