> ## Documentation Index > Fetch the complete documentation index at: https://learn.cleftnotes.com/llms.txt > Use this file to discover all available pages before exploring further. # Agent Access > Let an AI app read and search your Cleft notes without permission to change or share them Agent Access lets the AI app you already use read and search your notes. You pick the app by name. Cleft works out the setup and shows you only that one. Not sure which route is yours? [Set up your AI agent](https://learn.cleftnotes.com/user-guides/integrations/agent-access/agent-setup.md) starts from the agent's name, compares every route, and explains the words this page uses. ## What a connected app can and cannot do Connected apps get six read-only tools. With them, an app can: * List and count your notes. * Open a note. * Search note text. * List your tag names. * Export a note as Markdown, plain text, or JSON. It cannot create, edit, archive, delete, or share a note, and it cannot make a public link. Tags that differ only in capitalization count as one tag. A note tagged `Work` and a note tagged `work` appear as one tag with two notes, spelled the way you write it most often, and asking for either spelling finds both notes. Your notes and exported files keep the spelling you gave them. Cleft tells the app that your notes are your words rather than instructions to follow. The app should quote them and name the note each quote came from. Cleft skips unrelated Markdown files, notes from another account, and its own system notes. A password on a public share link protects the people you send that link to. It does not hide your own note from an app you connected. ## Turn on Agent Access Agent Access is in Cleft for Mac. Open **Cleft > Settings > Agent Access** and turn on **Let AI tools read your notes**. Nothing is shared with an AI app until you turn this on and add the setup to that app yourself. ## Choose where the app reads Under **Which notes should this connection read?**, choose one note source before you set up an app. | Source | Access | What it reads | | - | - | - | | **Local Export on this Mac** | Free | Cleft-authored Markdown files in your Local Export folder. It works offline and never reaches your Cleft account. | | **Cleft account library** | Plus | Your Cleft account over an encrypted connection. It works without exporting every note to this Mac, and needs an internet connection. | New Cleft Plus setups start with the account library. If you already chose Local Export, that choice stays selected. The selected source uses the connection name `cleft`. Its status line says what to fix before connecting. An unavailable account library never substitutes local notes for an online request. Changing the source does not update your AI app. Disconnect the old setup in that app, then follow Cleft's setup instructions for the new source. In Claude Desktop, uninstall the local Cleft extension before adding the account-library configuration. The extension continues reading Local Export until removed. ### Your Local Export folder On Mac, Cleft moves its own **Cleft Notes** folder once, with everything in it, into a folder that Cleft shares with the helper your AI app talks to. This lets the App Store version of Cleft serve your Local Export notes to an AI app. **Show in Finder** in Local Export settings opens the new location. If you export to a folder you chose, Agent Access says so and shows **Allow Folder Access**. Select it and confirm that folder once in the system picker. Your AI apps can then read the notes in it, without being able to change anything there. If that permission stops working, select **Renew Folder Access**. Choosing a different folder in Local Export asks for access again. ## Choose your app Under **Add it to your AI tool**, Cleft asks **Which app do you use?** It lists apps with verified setup instructions. Choose the app you use. Cleft shows the setup for the app you picked and nothing else. Before you pick, it says plainly that the app you choose can only read the notes from the selected source. **Claude Desktop.** Select **Install in Claude Desktop**. Cleft builds an extension and opens it in Claude Desktop, which shows you what it does and asks you to confirm. You never type a file path. The extension finds Cleft again by itself after you update, move, or reinstall Cleft. Cleft offers the install only when an app on this Mac can open an extension and Local Export is your selected, ready source. Otherwise you get the same setup as text, for the `claude_desktop_config.json` file. **Claude Code.** You get one command with your paths already filled in. Open a project folder in Terminal and run it there. It adds Cleft to that project only, and it never removes or replaces a server that already has the same name. **Codex.** You get one command to run in Terminal. It applies wherever you use Codex on this Mac rather than to one folder. **ChatGPT.** The same command. The ChatGPT desktop app, Codex, and the Codex editor extension read one shared configuration, so one command covers all three. **Cursor.** Select **Open in Cursor**. Cleft makes a setup link and opens it, and Cursor shows you what it adds and asks you to confirm. The link is under the button too, with **Copy setup link**, so you can open it yourself if nothing happens. When Cleft cannot find Cursor on this Mac, you get the setup as text instead, for `~/.cursor/mcp.json`. **VS Code.** You get one command to run in Terminal. It adds Cleft to your own VS Code setup, so it works in every folder you open. **Gemini CLI.** You get one command to run in Terminal. It adds Cleft for your user account, so it works wherever you run Gemini CLI on this Mac. **Zed.** You get a block of text for `~/.config/zed/settings.json`. Add it alongside the settings already in that file, then restart Zed. **OpenCode.** You get a block of text for the `opencode.json` file in your project. Add it alongside what is already there, then restart OpenCode. **Windsurf.** You get the setup as text, for `~/.codeium/windsurf/mcp_config.json`. Paste it in, then restart Windsurf. **Another tool.** You get the setup as text. Paste it into that tool's own MCP server settings, then restart the tool. Cleft makes no promise about a tool it has not checked, beyond the shape of the text it hands you. For any agent that can run commands, use [Agent Access from the command line](https://learn.cleftnotes.com/user-guides/integrations/agent-access/command-line.md). That route also works for scripts and agents absent from this list. Cleft says **Found on this Mac** or **Not found on this Mac** for Claude Desktop, Cursor, VS Code, and Zed. Those four ship an app it can look for. It says nothing either way about a command line tool, because there is no app on your Mac for it to find. Paths are hidden on screen by default, so the pane is safe to share. Select **Show paths** to see them. Copying the setup always copies the real values. The setup never contains a password, an integration key, or an account identifier. Cleft keeps the account-library key in your Mac's Keychain and reads it again for each request. ## Finish the setup and confirm it Under the app you picked, Cleft says how far its setup has got. The line reads one of these: * **Nothing set up yet.** * **Setup is ready below.** * Copied, with the app named, and a reminder to finish the step there and confirm here. * Handed to that app, with a reminder to confirm here once the app accepted it. * **Confirmed by you.** * **Needs attention**, followed by what changed. Cleft cannot see inside your other app, so it never claims an app is reading your notes. Run the command, paste the block, or accept the handover, then select the confirm button beside that line: **I installed it**, **I ran the command**, or **I updated the file**, depending on the app. The line then reads **Confirmed by you**. ## Repair a connection that stopped working If Cleft moves, your export folder changes, or you choose a different note source, the setup you already gave an app points at the old place. Cleft names each affected app on its own line in the pane, with its own fix: **Install again**, **Copy setup command again**, or **Copy configuration again**. Cleft names the exact entries to remove before you add the new ones, so you only remove what it added. Complete the step in the other app, then select **I removed the old entries and applied the setup** so Cleft can update what it remembers. ## Disconnect an app Turning Agent Access off stops Cleft offering new setup details. An app you already set up keeps reading until you disconnect it there. Once Cleft has handed out a setup, a **How to disconnect** section appears with the steps for each app. Cleft cannot run commands or edit another app's files for you, so you complete these steps yourself. * **Claude Desktop.** Open **Settings**, then **Extensions**, and uninstall Cleft if you installed the extension. For a text setup, remove `cleft` and `cleft-cloud` (if present) from `mcpServers` in `~/Library/Application Support/Claude/claude_desktop_config.json`, then restart Claude Desktop. If you used both routes, remove both. * **Claude Code.** Open each project folder where you registered Cleft in Terminal and run the removal commands below. * **Codex, ChatGPT, and the Codex editor extension.** Open `~/.codex/config.toml` and delete the Cleft sections. That one file serves all three. Delete Cleft from a project's own `.codex/config.toml` as well if you added it there. * **Cursor.** Open **Customize** in the sidebar and turn the Cleft server off. To remove it for good, open `~/.cursor/mcp.json` and delete the Cleft entries. * **VS Code.** Open the Command Palette, run **MCP: List Servers**, and remove Cleft. You can also run **MCP: Open User Configuration** and delete the Cleft entries there. * **Gemini CLI.** Run `gemini mcp remove -s user cleft` in Terminal, and `gemini mcp remove -s user cleft-cloud` if you added both sources. * **Zed.** Open `~/.config/zed/settings.json` and remove the Cleft entries from `context_servers`. * **OpenCode.** Open the `opencode.json` file in each project where you added Cleft and remove the Cleft entries from `mcp`. * **Windsurf and another tool.** Delete the Cleft entries from that tool's own MCP server settings. For Claude Code, in each project folder where you registered Cleft: ```bash theme={null} claude mcp remove cleft --scope local claude mcp remove cleft-cloud --scope local ``` The second command applies only when you added the account library. Select **Clear this record** when you have finished. It clears what Cleft remembers about that app. The steps above are what end the connection. ## Start with a prompt Connected apps can offer these Cleft starting points: * **Catch me up** finds recent themes and open threads. * **Find what I said** locates your words and names their source notes. * **Topic brief** gathers what you have said about a topic. ## Troubleshooting ### Cleft says Local Export is not ready Agent Access says what is in the way: * If Local Export is off, select **Open Local Export**, turn it on, and return to Agent Access. * If your export folder can't be reached and it lives on an external or cloud drive, connect the drive, then choose the folder again in Local Export. * If your notes export to a folder you chose, select **Allow Folder Access** and confirm the folder. * If the Cleft helper isn't installed on this Mac, reinstall or update Cleft to put it back. ### The account library is unavailable Agent Access says why the account library can't be chosen: * **Checking your Cleft Plus membership.** Cleft hasn't confirmed your membership yet. Connect to the internet, then select **Check again**. * **The account library needs Cleft Plus.** Select **Upgrade to Plus**, or keep using Local Export on this Mac, which works with every account. * **The account library isn't available in this version of Cleft.** Update Cleft, or use Local Export on this Mac. While Cleft is still confirming your membership after launch, it keeps your account-library choice but does not offer new setup until the check finishes. It does not switch the setup to Local Export during this check. If you choose the account library and it still isn't connected, select **Connect account library** in Agent Access so Cleft can set up the key it keeps in your Mac's Keychain. ### The tool reports that the backend is not configured Copy the current setup again. Remove the stale Cleft entries from the app first, using the names Cleft shows you. Cleft never replaces an existing configuration on its own. ### Your app is not on the list Pick **Another tool**. The setup Cleft hands you is the shape most MCP apps read. An app appears by name only after someone has checked that maker's current instructions. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.