Working with Mac apps
Configure access to supported Apple apps and understand per-action permissions.
In this topic
Mellow can give an agent specific access to Calendar, Reminders, Contacts, Notes, Mail, Messages, Maps and Location, Music, and Shortcuts. Use these integrations for structured work such as finding a calendar event, preparing an email draft, or completing a reminder.
Enable the apps a particular agent needs. The capability belongs to that agent; installing Mellow alone does not make every Apple app available to every conversation.
Enable an app and prove access
Open the agent editor, find its tools or abilities, and enable the Apple app group. macOS may then request its own permission. These are two separate gates: the Mellow agent capability and the operating system permission.
Begin with a narrow read, such as listing tomorrow's events or finding a reminder by title. Verify the selected account, calendar, or list before requesting a change. For messages, ask for a draft first so you can inspect the recipient and wording.
macOS permission reference
| App | macOS permission | Notes |
|---|---|---|
| Calendar | Calendars (Full Access) | |
| Reminders | Reminders (Full Access) | |
| Contacts | Contacts | |
| Notes | Automation → Notes | |
| Automation → Mail | ||
| Messages | Full Disk Access and Automation → Messages | macOS doesn't pop up a request for Full Disk Access. Turn it on yourself in System Settings. |
| Maps & Location | Location | |
| Music | Automation → Music | |
| Shortcuts | None | Individual shortcuts may ask for their own permissions |
A Permission needed state can persist after the Mellow toggle is enabled. Open the matching Privacy & Security setting, grant access, and retry. Full Disk Access is enabled in System Settings rather than through an ordinary consent prompt.
Review changes that matter
Sending Mail or Messages and deleting Calendar events or Reminders require an approval at execution time. An automatic draft policy does not silently authorize sending. Review the exact recipient or object in the approval, not only the natural-language task description.
Recurring events need a specific occurrence. Notes containing attachments are protected from append operations that could damage their contents; create a separate note or open the original instead. Shortcuts can display their own dialogs and wait for your input, and can have effects beyond the summary shown in Mellow.
Available operations
| App | Tools |
|---|---|
| Calendar | calendar_list, calendar_events, calendar_create_event, calendar_update_event, calendar_delete_event, calendar_open_event |
| Reminders | reminders_lists, reminders_fetch, reminders_create, reminders_update, reminders_complete, reminders_delete, reminders_open |
| Contacts | contacts_me, contacts_search, contacts_list, contacts_get, contacts_create, contacts_update, contacts_open |
| Notes | notes_folders, notes_list, notes_search, notes_read, notes_create, notes_append, notes_open |
mail_mailboxes, mail_list, mail_read, mail_search, mail_compose, mail_reply, mail_move, mail_set_status, mail_thread | |
| Messages | messages_conversations, messages_read, messages_unread, messages_search, messages_send |
| Maps & Location | location_current, location_geocode, location_reverse_geocode, maps_search, maps_explore, maps_directions, maps_eta, maps_open |
| Music | music_now_playing, music_playback, music_set_volume, music_playlists, music_search, music_play |
| Shortcuts | shortcuts_list, shortcuts_run |
The table describes built-in operation names. It is not a promise that each one is available to every caller. Agent capabilities and operation permissions are checked when a call executes.
Configure an agent declaratively
The apple_apps capability is a complete replacement list, not an additive patch. An empty list disables every Apple app for that agent.
agents:
- name: Personal Organizer
capabilities:
tools_enabled: true
apple_apps: [calendar, reminders, contacts]
Use the stable app identifiers shown by Mellow's configuration editor. The common values are calendar, reminders, contacts, notes, mail, messages, maps, music, and shortcuts.
Connection boundaries
Built-in Apple app tools are excluded from the external MCP tool catalog and rejected for outside HTTP callers. A remote MCP connection cannot register a replacement using one of these protected tool names. Turning off an app also removes it from the agent's available tools and blocks direct calls by that agent.
These restrictions are distinct from native screen automation. Review Computer Use separately when enabling an agent to operate applications through the desktop.
When an operation fails
Permission denied: check both the current agent's app group and macOS permission. A permission granted to a different build may need review after signing or installation changes.
Item not found: search again and use the current identifier returned by the app. Names and positions can change.
Mail draft exists but was not sent: inspect whether sending was requested and approved. A saved draft is a valid draft result.
Messages delivery is uncertain: inspect the conversation before retrying. Do not turn uncertainty into a duplicate send.
Shortcut appears stalled: look for a dialog in Shortcuts or the target app. Cancelling the Mellow run can stop the shortcut; it does not necessarily undo actions already completed.
See Tools and permissions for capability selection and Security and data boundaries for the broader model.
Continue exploring · Connect your workspaceBrowser tasks →Give an agent a browser session and review navigation, page context and actions.