---
title: MCP tool reference - Keeploop
url: https://keeploop.app/mcp-tools
description: Every tool web and phone AI apps can call through Keeploop's MCP connector: what it does, whether it reads or writes, its side effects and when it asks on your Mac.
docs_index: https://keeploop.app/llms.txt
---
MCP 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_monitor` and `cancel_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](https://keeploop.app/connect).

## 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.

58 tools: 46 Read, 9 Write, 3 Sensitive write.

- [Mail](https://keeploop.app/mcp-tools#mail)
- [Calendar](https://keeploop.app/mcp-tools#calendar)
- [Drafts and sending](https://keeploop.app/mcp-tools#drafts)
- [Monitors](https://keeploop.app/mcp-tools#monitors)
- [Messages, Slack, Notes and other sources](https://keeploop.app/mcp-tools#sources)
- [Setup and account](https://keeploop.app/mcp-tools#setup)
- [Cards](https://keeploop.app/mcp-tools#cards)

## Mail

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

A reply's recipients come from the message being answered. A new email, a draft change or a delete asks the user every time, showing the account and every recipient, unless a rule marked Only over remote access says Auto. 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). |
| `save_draft` | Saves a new email in Mail's Drafts, from one of the user's accounts to the recipients given. | Write | Creates a draft in Mail. Never sends. | Yes, every time, unless a rule marked Only over remote access says Auto. Rules can block it per person, label, account or AI app. |
| `update_draft` | Replaces an existing draft with new text, subject or recipients. | Write | Creates the replacement draft and deletes the original. Never sends. | Yes, every time, and flags a change of recipients, unless a rule marked Only over remote access says Auto. |
| `delete_draft` | Deletes one draft. | Write | Deletes the draft from Mail. It cannot be undone. | Yes, every time, showing the draft's subject and recipients, unless a rule marked Only over remote access says Auto. |
| `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. |
| `send_email` | Sends a new email now, from one of the user's accounts to the recipients given. | Sensitive write | Sends email from the user's account. | Yes, every time, showing the account and every recipient, unless a rule marked Only over remote access says Auto. |

## 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, save_draft, send_reply, send_email 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: 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 reply in a Mail thread under the user's rules. A new email, a draft change or a delete from one asks the user on the Mac every time, showing the account and every recipient, unless a rule marked Only over remote access says Auto.

## 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 `-32001` for requests other than tool calls. `initialize`, `ping` and `tools/list` still 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/list` returns 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](https://keeploop.app/privacy) and [Security](https://keeploop.app/security).

Questions: [help@keeploop.app](mailto:help@keeploop.app).