KeeploopMCP REFERENCE
Keeploop MCP tools
Every tool a web or phone AI app can call through Keeploop. What it does, what it changes, and when it asks on the Mac first.
Connecting
- Endpoint:
https://mcp.keeploop.app/mcp. The same URL for every user. - Auth: OAuth 2.1 with PKCE (S256) and dynamic client registration. Client ID metadata documents also work. Scope:
keeploop. Metadata:https://mcp.keeploop.app/.well-known/oauth-authorization-server. - Sign-in: the user signs in to Keeploop with a code sent to their email.
- Approval: the first time, the user approves the AI app on their Mac. The Mac and the browser show the same code. Removing the app on the Mac revokes it.
- Requirements: the Keeploop Mac app on an Apple Silicon Mac with macOS 26 or later, Keeploop Pro or the free trial, and the Mac on with Keeploop running.
- Writes follow the Mac: by default a web or phone AI app gets what apps on the Mac get, under the same permissions. On a new install Mail and Calendar are Read only, so the only write tools listed are
create_monitorandcancel_monitor, which record matches and notify the user. Draft, send and calendar tools appear only after the user sets Mail to Read and write or Calendar to Read and propose on the Mac. The user can instead set each source to Read only or Read and write for web and phone apps alone, in Keeploop > Settings > Remote access. The list also follows the sources the user turned on and any access profile for that app.
Setup steps for each AI app: Connect a web or phone AI.
How to read the tables
- Read: reads data. Changes nothing and sends nothing.
- Write: changes something on the Mac, such as a draft, a monitor or a calendar proposal. Never sends anything to another person.
- Sensitive write: can send email from the user's account.
- A tool that both reads and writes is listed as a write. No Read tool sends, shares or posts anything.
- Asks on the Mac first: Keeploop's permissions decide each write by action, person, label, account and AI app: Block, Ask or Allow. Ask means the call waits for the user's click on the Mac. Telling the AI "yes" never counts. The defaults are shown; the user can change them.
54 tools: 46 Read, 6 Write, 2 Sensitive write.
- Calendar
- Drafts and sending
- Monitors
- Messages, Slack, Notes and other sources
- Setup and account
- Cards
Read Apple Mail's own store on the Mac, limited to the accounts the user chose.
| Tool | What it does | Class | Side effects | Asks on the Mac first |
|---|---|---|---|---|
list_accounts | Lists the Mail accounts Keeploop may read, with their labels. | Read | None | No |
list_categories | Lists the labels the user gave accounts and contacts, such as Personal and Work. | Read | None | No |
search_mail | Searches mail by sender, subject, date, account or label, and optionally body text. | Read | None | No |
get_email | Reads one message in full: headers, recipients, attachments and body text. | Read | None | No |
get_thread | Lists every message in the same conversation as one message, oldest first. | Read | None | No |
find_attachments | Finds attachments by file name, kind, sender, date or account. | Read | None | No |
read_attachment | Reads one attachment as text, or as an image the AI can see. | Read | None | No |
awaiting_reply | Lists threads where someone is waiting on the user, or the user is waiting on someone. | Read | None | No |
Calendar
Read the calendars the user shared. The write tools appear only when the user sets Calendar to Read and propose on the Mac.
| Tool | What it does | Class | Side effects | Asks on the Mac first |
|---|---|---|---|---|
list_calendars | Lists the calendars the user shared with Keeploop. | Read | None | No |
list_events | Lists events in a time range across those calendars. | Read | None | No |
get_event | Reads one event with its attendees and their answers. | Read | None | No |
find_free_time | Finds open slots of a given length inside working hours. | Read | None | No |
find_invites | Lists meeting invites found in mail and whether they still need an answer. It never accepts or declines. | Read | None | No |
list_proposals | Lists events proposed with propose_event and what became of each. | Read | None | No |
propose_event | Proposes an event for the user's calendar. Nothing is added until the user taps Add on the Mac. | Write | Shows a notification on the Mac. Adds the event only after the user taps Add. Proposals expire after 24 hours. | Always. The event is added only when the user taps Add. |
propose_reschedule | Finds new times for a meeting and saves a reply to the invite that lists them. | Write | Saves a reply draft in Mail. Sends nothing and does not change the calendar. | Yes, by default. The draft goes through the Draft permission (Ask). |
cancel_proposal | Withdraws a pending proposal. | Write | Removes the proposal's notification on the Mac. | No. Refused when the user blocks calendar changes. |
Drafts and sending
Replies only. Recipients always come from the message being answered, never from the AI. Draft and send tools appear only when the user sets Mail to Read and write on the Mac.
| Tool | What it does | Class | Side effects | Asks on the Mac first |
|---|---|---|---|---|
get_voice_profile | Returns a short description of how the user writes, for drafting in their voice. | Read | None | No |
list_drafts | Lists drafts in the shared accounts. | Read | None | No |
save_reply_draft | Saves a reply to an existing message in Mail's Drafts. | Write | Creates a draft in Mail. Never sends. | Yes, by default (Draft permission: Ask). |
send_reply | Sends a reply to an existing message now. | Sensitive write | Sends email from the user's account. If the send is refused or fails, the reply stays in Drafts. | Yes, by default (Send permission: Ask). Rules can block it per person, label, account or AI app. |
Monitors
Monitors watch for new items on the Mac, record matches and can notify the user. They never send anything. create_monitor and cancel_monitor are listed by default, even with Mail at Read only.
| Tool | What it does | Class | Side effects | Asks on the Mac first |
|---|---|---|---|---|
list_monitors | Lists the user's monitors and their status. | Read | None | No |
check_monitor | Returns the matches a monitor recorded, optionally only the new ones. | Read | None | No |
create_monitor | Watches mail, texts, calendar, Slack or Notes for new items that match, and records each match. | Write | Creates a monitor on the Mac. Each match can notify the user. It never sends, changes or deletes anything. | No, by default (Monitor permission: Allow). The user can set it to Ask or Block. |
cancel_monitor | Stops a monitor. Its recorded matches stay readable. | Write | Stops the monitor. | No. Refused when the user blocks monitors. |
Messages, Slack, Notes and other sources
Each source's tools appear only when the user turns that source on in Keeploop. All are read only from web and phone AI apps.
| Tool | What it does | Class | Side effects | Asks on the Mac first |
|---|---|---|---|---|
search_messages | Searches iMessage, SMS and RCS messages on the Mac. | Read | None | No |
get_conversation | Reads the newest messages in one Messages conversation. | Read | None | No |
search_whatsapp | Searches messages the WhatsApp desktop app stored on the Mac. | Read | None | No |
get_whatsapp_chat | Reads the newest messages in one WhatsApp chat. | Read | None | No |
search_slack | Searches the Slack messages Keeploop keeps on the Mac. | Read | None | No |
get_slack_thread | Reads one Slack thread with its replies. | Read | None | No |
list_slack_channels | Lists the Slack conversations Keeploop can read. | Read | None | No |
search_notes | Searches Apple Notes by title and text. Locked notes are never read. | Read | None | No |
get_note | Reads one Apple Note in full. | Read | None | No |
search_contacts | Searches Contacts by name, company, email or phone. | Read | None | No |
get_contact | Reads one contact in full. Contact notes are never read. | Read | None | No |
recent_calls | Lists phone and FaceTime call history. | Read | None | No |
get_voicemails | Reads voicemails with their transcripts. | Read | None | No |
recent_notifications | Lists notifications apps posted on the Mac. | Read | None | No |
notification_apps | Lists which apps posted notifications, with counts. | Read | None | No |
Setup and account
Help the AI explain what it can do, and why something does not work.
| Tool | What it does | Class | Side effects | Asks on the Mac first |
|---|---|---|---|---|
check_setup | Checks each part of the Keeploop setup and says how to fix what fails. | Read | None. A few checks test network connections (the connection service, ntfy, Slack). | No |
check_permissions | Reports which macOS permissions Keeploop has and what is missing. | Read | None | No |
get_policy | Reads the user's permission rules (Block, Ask or Allow) with plain summaries. | Read | None | No |
explain_policy | Says what would happen if the AI tried an action now, and why. | Read | None | No |
explain_access | Says what this connection can read, and why something is hidden. | Read | None | No |
get_settings_summary | Summarizes what this connection can read now. | Read | None | No |
Cards
Interactive cards for AI apps that show them (MCP Apps). Tools marked card only are called by the card, not the model.
| Tool | What it does | Class | Side effects | Asks on the Mac first |
|---|---|---|---|---|
keeploop_inbox | Opens Keeploop's Inbox card: replies owed, today's events, monitors and recent mail. | Read | None | No |
show_mail | Shows up to 8 emails as a card. | Read | None | No |
show_today | Shows today's brief: next events, replies owed and monitor matches. | Read | None | No |
show_free_time | Shows open calendar slots as a card the user can pick from. | Read | None. Adding a slot uses keeploop_card_action. | No |
show_draft | Shows a draft as a card with Save and Send buttons. It saves and sends nothing itself. | Read | None. Its buttons use keeploop_card_action. | No |
keeploop_card_thread | Card only: loads one conversation for a card. | Read | None | No |
keeploop_card_status | Card only: reports the state of a card button's run. | Read | None | No |
keeploop_card_action | Card only: runs the tool behind a card button: save_reply_draft, send_reply or propose_event. | Sensitive write | Those of the tool it runs, which can send email. | The same as the tool it runs. Each is checked exactly as a direct call. |
Not available from web and phone AI apps
These work only from AI apps on the Mac itself: new emails to any address, editing or deleting drafts, texts, Slack posts, notes, saving attachments to disk, waiting for new mail, editing or deleting monitors, and any change to permissions or settings. A web or phone AI app can at most reply in an existing Mail thread, under the user's rules.
Errors
Errors come back as a tool result with isError: true and a plain sentence the AI can repeat to the user. Requests other than tool calls get a JSON-RPC error with the same sentence.
- Mac off, asleep or Keeploop not running
Your Mac is offline or asleep, so Keeploop can't reach it. Wake the Mac and make sure Keeploop is running, then try again.
JSON-RPC code-32001for requests other than tool calls.initialize,pingandtools/liststill answer, so the connection stays healthy. Nothing is queued for later.- No Mac paired yet
Keeploop isn't connected to a Mac yet. Open Keeploop on your Mac and pair it in Settings > Remote access.
- A tool call the Mac did not finish within 55 seconds
Your Mac didn't answer in time. The result is unknown; check on your Mac before retrying.
- Write tools not allowed for this connection
send_reply is off for remote apps: Mail is Read only. The user can change it on the Mac in Keeploop > Settings > Remote access.
- Blocked by the user's permissions
send_reply is blocked for remote apps by Keeploop's permissions. The user can change them on the Mac in Keeploop > Settings > Permissions.
A plain reason follows.- The user said no on the Mac
The user said no on this Mac. Nothing was done; do not retry unless they ask you to.
- A tool that works only on the Mac
send_email is not available to remote apps. It works from apps on the Mac itself.
- Keeploop was updated while the app was connected
Keeploop was updated. Reconnect it in your AI app.
- No Pro or trial on the account
Remote access needs Keeploop Pro. Open Keeploop on your Mac to see your options.
tools/listreturns no tools until the user has Pro or the trial.- Too many requests at once
Too many requests to your Mac at once. Try again in a moment.
HTTP 429, JSON-RPC code-32002,Retry-After: 2.
Limits
- 8 requests in flight per Mac.
- 55 second deadline per request, under the 60 second timeout many MCP clients use. An Ask approval on the Mac must come within it.
- Request body up to 512 KB. Result up to 8 MB.
Data
Keeploop reads the user's data on their Mac. Requests and results pass through Keeploop's connection service in memory on the way between the AI app and the Mac. They are never stored. Once an AI app receives a result, that app's own data policy applies. Details: Privacy policy and Security.
Questions: [email protected].