Manual

1. Getting started

Accounts live in Amazon Cognito; the app itself never sees your password.

1. Press Sign in and choose Sign up on the page that opens. Only pre-approved e-mail addresses are accepted; anything else is refused on the spot. The name is optional.
2. Choose a password of at least 12 characters with upper- and lowercase letters, a digit and a symbol.
3. Verify your e-mail with the code Cognito mails you.
4. Set up your authenticator app (1Password, Apple Passwords, Google Authenticator, Authy, Microsoft Authenticator…) by scanning the QR code and entering one code. This is required for every account.

Signing in is always e-mail + password + authenticator code. Forgot the password? Use Forgot your password? on the sign-in page. New phone? Security → Set up / replace authenticator shows a fresh QR code. Locked out entirely? The operator resets it on the command line (see Operations). The app has five tabs: Accounts (mailboxes), Calendars, Outbox (mail waiting for your approval), Connect Claude (tokens and connected apps), Activity (everything that happened) and Security (sessions).

2. Apple Mail (iCloud)

Create an app-specific password

Apple does not let third-party software use your Apple ID password. You need an app-specific password, which requires two-factor authentication to be on for your Apple ID (it almost certainly is).

1. Go to appleid.apple.com and sign in.
2. Open Sign-In and Security → App-Specific Passwords.
3. Click Generate an app-specific password, name it WebMail / Private Office MCP, and copy the 16-character password (xxxx-xxxx-xxxx-xxxx). It is shown only once.

You can revoke it on the same page at any time; that instantly cuts Claude off from the mailbox.

Add the account

1. In the app, Accounts → Add mail account and choose the preset iCloud Mail. The hosts and ports fill in:

2. Email address: your iCloud address (you@icloud.com, you@me.com or a custom domain on iCloud+). IMAP username: the full address — for custom domains use the primary iCloud address as the username. IMAP password: the app-specific password. Leave the SMTP fields empty; they inherit the IMAP values.
3. Tick Read-only if Claude should only ever read this mailbox. You can change this later from the account card.
4. Save, then press Test on the card. You should see IMAP OK — INBOX has … messages · SMTP OK — authenticated.

What Claude can do with it

• Search and read — folders, search by subject, sender, recipient and date (the default, fast) or deep inside the message text (scope: body, slower on big folders), full messages, attachment download (images shown inline, other files as attachments; 4 MB each).
• Flags and replies — Claude sees each message's flags (read, replied, flagged, forwarded, your own tags/keywords) and can filter on them: “what haven't I answered this week?”, “show my flagged mail”. When a reply goes out through this app, it is noted in a reply log and the original is marked as answered in your mailbox, so “did I reply to Anna?” is answered at once. Replies you write in Mail.app are recognised by the same answered mark. The log keeps a year and is erased with the mail account.
• Link — every message Claude finds comes with a link of the form …/mail/<account>/<folder>/<uid>. Put it in a to-do, a note or a calendar entry: tapping it opens that one message here in the app (after sign-in, if needed). Only the account's owner can open it; everyone else sees “not found”.
• Draft — writes into your Drafts folder; you open it in Mail.app, edit and send yourself.
• Send — by default Claude cannot send. It composes, parks the mail in Drafts and adds it to your Outbox; see below. The same goes for a draft you wrote yourself in Mail.app: “send my draft to Anna” queues it for your approval.
• File — archive, move between folders, flag/unflag, mark read/unread, create folders. Deleting folders needs your explicit confirmation.
• Nothing at all beyond reading when the account is read-only — including marking a message as read. The one exception you can grant is Allow archiving on the account card: Claude may then move messages to the archive folder, and still nothing else.

The Outbox

When Claude wants to send, the exact message is saved to your Drafts and listed in Outbox with recipients, subject and a preview. Send now puts exactly those bytes on the wire and files a copy in Sent; Discard drops the request and leaves the draft. Queued mail expires after 7 days. The switch above the list can allow direct sending — it is off by default and every change is logged and mailed to you.

Auto-approved recipients (also in the Outbox tab): addresses Claude may mail without your click, for one mailbox or all of them, at most 50. A mail goes out at once only if every recipient — To, Cc and Bcc — is on the list for the sending mailbox; one other address and the whole mail waits in the Outbox as usual. Only you can change the list, here in the app; Claude has no tool for it. Every change is logged and mailed to you, and every mail sent this way appears in your Activity log.

Classifying mail and Triage

Ask Claude “what is important in my mail?”, “anything interesting since Monday?” or “show me all business mail”. It ranks your recent mail across all accounts with the TypeSafe AI classifier and gives you a list with a link to each message. For this, the sender, subject and the beginning of each message's text are sent to TypeSafe AI. Attachments are never sent, and nothing in your mailbox changes.

Claude can also suggest what to do with each message: archive, move, star, tag, mark read or move to Trash. Suggestions wait under Triage. Tick the ones you agree with and press Apply, or reject them. Claude cannot apply them itself. A message that has moved since the suggestion was made is skipped. Suggestions expire after seven days, and every applied action is in your Activity log.

Troubleshooting

• “Authentication failed” — you entered your Apple ID password; iCloud only accepts app-specific passwords here. Generate one as above.
• No app-specific passwords option — turn on two-factor authentication for your Apple ID first (Settings → your name → Sign-In & Security on an iPhone).
• Custom domain address rejected as username — sign in with your primary @icloud.com address as the IMAP username and keep the custom domain as the account's e-mail address.
• Sent mail missing from Mail.app — the copy is filed in the folder iCloud marks as Sent; give Mail.app a moment to sync.
• “Message not found” — message ids (uids) are per folder; ask Claude to search again in the right folder.

3. Apple Calendar (iCloud)

Apple Calendar is reached over CalDAV, an open standard iCloud supports fully: reading, creating, changing and deleting events, including recurring events, reminders and invitations. Each iCloud calendar (Home, Work, Family…) is added separately so you can decide per calendar what Claude may do.

Add a calendar

1. Use the app-specific password from the mail section, or generate a second one named WebMail / Private Office MCP Calendar.
2. Calendars → Add calendar, keep the source Apple iCloud Calendar:

3. Press Connect & list calendars. After a moment a dropdown shows every calendar on the account. Calendars you subscribed to in Calendar.app appear marked subscription, read-only.
4. Pick one, give it a label (e.g. Work), tick Read-only if Claude should only look, and Save — or press Add all calendars to add every calendar on the account in one go, each named after itself (the Label field then acts as an optional prefix). Subscribed calendars are added read-only.
5. Test on the card confirms the sign-in and whether the calendar has upcoming events.

What Claude can do with it

• List and search events in any window up to a year, recurring events expanded into their occurrences, with times in the event's own zone.
• Create events — title, start/end (Claude works in your time zone and repeats it back), all-day events, location, notes, a recurrence rule (“every Monday”, “first of the month for a year”) and a reminder.
• Change events — any of those fields; a recurring event is changed as a series. Edits use the calendar server's version check, so a change you make in Calendar.app at the same moment is never silently overwritten.
• Delete events — only after you have confirmed the title and date.
• Invite people — when an event has attendees, iCloud itself e-mails the invitations the moment the event is saved. Claude is instructed to show you the attendee list and wait for your approval before doing so. If you would rather keep this impossible, mark the calendar read-only or ask Claude to create the event without attendees and add them in Calendar.app.

Events created by Claude show up in Calendar.app on all your devices within a minute, like any other iCloud change.

ICS / webcal subscriptions

Any public calendar link — public holidays, school terms, a team calendar from another tool — can be added with the source ICS / webcal subscription: paste the webcal:// or https://…ics link and Save. Feeds are read-only, must be public (no passwords in the link) and at most 5 MB. To find the link of a calendar you already subscribed to in Calendar.app: right-click the calendar → Get Info → the URL field.

Troubleshooting

• “Sign-in failed” — same cause as for mail: use an app-specific password.
• A calendar is missing from the list — reminders lists are not calendars and are skipped; calendars shared with you appear only if iCloud exposes them, often as read-only.
• “The calendar server refused the event” — usually a read-only calendar on the server side (a subscription or a shared calendar without write access). Pick another calendar.
• Times are off by an hour — tell Claude your time zone (Europe/Berlin, America/New_York…). Wall-clock times without a zone are treated as UTC.
• “The event changed on the server while editing” — you or a device edited it at the same time; ask Claude to fetch and retry.

4. Apple Notes

Claude can read and add Apple Notes from two places: notes kept in one of your mail accounts, and the iCloud folders you share through the Notes relay on your Mac. It can never edit or delete a note.

Notes in a mail account

The Notes app stores these as ordinary messages in the account's Notes folder, so they come along with the mailbox you already added. Claude reads and adds them live.

1. Switch on Notes for the mail account. On iPhone: Settings → Apps → Mail → Mail Accounts → the account → Notes. On Mac: System Settings → Internet Accounts → the account → Notes.
2. In the Notes app the account now has its own section. Notes you write there are the ones Claude sees.

iCloud notes (Mac relay)

Apple offers no server access to iCloud notes. The small Notes relay app runs in your Mac's menu bar and does the work there:

1. Build or install NotesRelay.app (in the repository under mac/NotesRelay, ./scripts/bundle.sh) and open it.
2. Choose Sign in…, enter this server's address and sign in with your usual e-mail, password and authenticator code.
3. Allow access to Notes when macOS asks, then tick the folders Claude may read. Nothing is shared until you tick a folder.

Every ten minutes while the Mac is awake (and right after it wakes), the relay sends new and changed notes from those folders, encrypted, and removes notes you deleted or unshared. What Claude sees is therefore as fresh as the last sync, and Claude says so. A note Claude adds to iCloud is queued and appears in Notes at the next sync. The relay puts it into the folder Claude named if that folder is shared, otherwise into a shared folder called Notes.

The Notes tab in the app shows the connected Mac, the last sync and queued notes. Its Read-only switch stops Claude from queuing new notes, and Disconnect & delete synced notes removes everything the relay sent. Signing out in the relay does the same.

What Claude can do

• List and search notes by title or text, across every source at once or one at a time. Mail-account notes come with a link that opens them in this app.
• Read a note in full. Reading never changes it.
• Add a new note with a title, paragraphs and bullet or numbered lists.

A read-only mail account refuses new notes too. Every note tool call appears under Activity → Notes tools, with the account but never the note's text.

5. Guardrails

Under Guardrails you write rules, in plain language, that the server enforces on every tool call before anything happens — independent of what the model remembers or intends. Each rule applies to all tools or to the ones you tick, and has a mode:

• Remind — the rule is placed in Claude's instructions at connect time and prepended to every matching tool result. For style and preference rules: “Write German mails with Sie”, “Never archive mail from my accountant”.
• Confirm — a matching call is refused with the rule text; Claude has to follow it (typically: ask you) and then call again with an explicit acknowledgement of the rule id. For “ask me first” rules: “Before sending to anyone outside my company, show me the recipients and wait for my OK.”
• Block — matching calls are always refused, and Claude is told not to retry. For hard limits: “Never delete calendar events” (tick delete_event), “No sending at all from the Private account”.

Every refusal and every reminder is recorded in your Activity log (kind “Settings” for rule changes; the tool call itself shows denied with the rule id). Claude can read the current rules with list_guardrails. Guardrails complement, not replace, the structural safeguards — read-only accounts and the Outbox stay as they are.

6. Connecting Claude

Claude Code

1. Connect Claude → Create token, name it after the machine. Copy the token — it is shown once.
2. Run the command shown, which looks like:

claude mcp add --transport http --scope user private-office <MCP URL> --header "Authorization: Bearer wmcp_…"

Tokens expire after 90 days by default; revoke any time from the same tab.

claude.ai and the Claude desktop app

1. Settings → Connectors → Add custom connector, paste the MCP URL from Connect Claude, press Connect.
2. You land on this server's consent screen: sign in with e-mail, password and second factor.
3. The app now appears under Connected apps; Disconnect revokes it immediately.

When the server's address changes

Always connect to the MCP URL shown under Connect Claude. It ends in .cloudfront.net/mcp, the address that runs through the server's firewall. If the server moves (as it did when it was put behind CloudFront), the old address answers 404 Not found. Your accounts, tokens and data stay exactly as they were; only the connection needs the new address:

• Claude Code: claude mcp remove private-office, then run claude mcp add again with the new URL. Your existing token keeps working.
• claude.ai / desktop: remove the custom connector, add it again with the new URL and sign in once more.
• Notes relay on the Mac: sign out, then sign in with the new server address.

Clients cache the tool list when they connect. After the server is updated, toggle the connector off and on (or start a new conversation) to see new tools. A good first prompt: “What's in my inbox, and what's on my calendar this week?”

7. Safety & privacy

• Logged: sign-ins and failures, token and connector changes, mailbox and calendar changes, Outbox decisions, and every tool call Claude makes — tool, account or calendar, folder/uid/recipients/subject or event title and time, outcome, duration. Never logged: message bodies, attachments, event notes, passwords, codes.
• Stored encrypted: mail and calendar passwords. Your sign-in password and authenticator secret live in Cognito, never here. Tokens are stored only as hashes.
• Alerts: every new sign-in, failed attempt, new token, new connector, factor change and operator actions is mailed to you.
• Revoking: delete a token or disconnect an app (instant); revoke the app-specific password at Apple (instant, for both mail and calendar); Security → Sign out everywhere; or delete the account/calendar from the app, which erases its credentials.
• New phone: Security → Set up / replace authenticator. Locked out: the operator resets your two-factor setup on the command line and Cognito asks for a new authenticator at the next sign-in.

8. Operations (command line)

There is no administrator in the web app: everybody has the same rights over their own data and nothing else. The few things that must be done to a user happen on the command line, from the repository, with AWS credentials for the stage:

cd sst && npm run user -- <command> [email] --stage dev

• list — users in the pool with status and MFA state
• reset-mfa <email> — clear the authenticator; the user sets up a new one at the next sign-in
• signout <email> — revoke every Cognito session and refresh token
• disable <email> / enable <email> — switch an account off or on (sign-in and every token stop working while disabled)

Everything else — passwords (via Forgot your password?), sessions, tokens, connected apps, accounts, calendars — each user manages for themselves in the app.