THE CONNECTION GUIDE

A way to say ayy.

ayy has two sides: a native iPhone inbox for you, and MCP tools for your agents. The app is in development. This guide describes the first self-hosted version.

1. Connect your inbox

On a service with email sign-in enabled, choose Continue with email in the iPhone app. Enter the eight-digit code to create your inbox or return to your existing conversations. For your own deployment, open “Using your own server?” and enter its HTTPS URL.

Server operators enable email sign-in with a verified Resend sender, a RESEND_API_KEY, and a random AUTH_SECRET of at least 32 characters. The default sender is app@ayy.fyi; use a sender you control for your own deployment. Hosted sign-up at api.ayy.fyi is not live yet.

You can also provision a personal access key for a self-hosted inbox and choose Connect with a personal key. Personal keys belong to you. Never give yours to an agent.

cd service
npm install
npm run build
npm run migrate
npm run create-user -- "Your name"
npm start

The service stores conversations in Neon Postgres and can run on Vercel. Configure DATABASE_URL and run the database migration before starting it. Use a separate database branch for development and previews. The setup command shows your personal key once.

2. Give each agent its own connection

In ayy, open Agents → Connect an agent. Give it a name, choose a color, and copy its key. You can mute notifications or revoke the connection from the same screen.

3. Add ayy to your MCP client

For clients that support remote MCP with custom headers, use your service’s /mcp endpoint. Replace both placeholders below with your actual service URL and agent key.

{
  "mcpServers": {
    "ayy": {
      "url": "https://YOUR-SERVICE/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_KEY"
      }
    }
  }
}

For clients that require a local stdio connection, run the adapter included in the service repository:

{
  "mcpServers": {
    "ayy": {
      "command": "node",
      "args": ["/absolute/path/to/service/dist/stdio.js"],
      "env": {
        "AYY_URL": "https://YOUR-SERVICE",
        "AYY_AGENT_KEY": "YOUR_AGENT_KEY"
      }
    }
  }
}

Four tools. One conversation.

• 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. Poll with backoff while waiting.
• ayy_reply adds context to an existing thread.
• ayy_list_alerts retrieves the agent’s recent conversations.

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({
  title: "Ready to ship?",
  body: "Open a pull request for the onboarding changes?",
  kind: "approval",
  idempotency_key: "onboarding-pr-v1"
})

Prefer HTTP?

Send the same fields directly to the API:

curl https://YOUR-SERVICE/v1/agent/alerts \
  -H "Authorization: Bearer $AYY_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Report ready","body":"Your shortlist is ready.","kind":"update"}'

Push notifications

Push requires an Apple Developer account, an app signed with the push entitlement, and APNs credentials configured on your service. Without those, the inbox still refreshes while the app is open. Quiet hours, agent muting, and message preview settings are enforced by the service.

For setup help, email help@ayy.fyi. App feedback goes to app@ayy.fyi.