Beta guide

Before installation

• Confirm that the website, release manifest, and DMG show the same version, arm64 architecture, and SHA-256.
• Stop if the checksum differs or macOS reports an unknown developer.
• Never bypass Gatekeeper or disable macOS security controls.
• The bridge and support will never ask for your Mac password, Apple password, API key, or Keychain secret.

Install

1. Open the DMG normally.
2. Drag MailCalendarBridge to the Applications link.
3. Eject the DMG and open the app from Applications.
4. Confirm that the bridge window and envelope/clock item appear.

Authorize the secure local connection

The app and helper share one device-bound Keychain secret. Always handle a macOS dialog yourself. Choose Always Allow only when the displayed helper path is exactly /Applications/MailCalendarBridge.app/Contents/Helpers/MailCalendarMCP.

Connect Calendar and Mail

1. Grant full Calendar access through the macOS dialog.
2. Refresh Mail accounts and respond to the Automation dialog yourself.
3. Select only the Mail accounts and individual calendars the bridge may use.
4. No selection means the related tools deny access.

Register the MCP client

codex mcp add apple-mail-calendar -- \
  /Applications/MailCalendarBridge.app/Contents/Helpers/MailCalendarMCP

Then start a new task and run bridge.health. A healthy connection reports authenticated-unix-ipc.

Troubleshooting

1. Open the main window.
2. Select Run under Local diagnostics.
3. Export the content-free JSON only when support requests it, and inspect the file yourself before sharing it.

Manual updates and rollback

The first beta has no automatic updater. Before replacing the app, make a uniquely named copy. Rollback is allowed only when both release manifests declare the same stateCompatibility and the version is not older than rollbackBaseline. Never repeat a mutation with an operation_in_doubt status.

Remove safely

1. Turn off Launch at Login and quit the app.
2. Run codex mcp remove apple-mail-calendar.
3. Move the app and explicit backups to the Trash.
4. Revoke Calendar and Mail Automation permissions if desired.
5. If desired, remove only the specifically named bridge items from Application Support, Preferences, and Keychain.