AI agents (Claude, ChatGPT, Gemini, Grok…)
Let Claude, ChatGPT, Gemini, Grok and other AI agents search, show and organise your files through Folia Files, with every change validated by you and undoable.
On this page
AI agents such as Claude (the Mac app), ChatGPT, Gemini, Grok, Claude Code, Codex, Cursor or VS Code can use Folia Files through MCP (the Model Context Protocol). The agent thinks; Folia shows and does:
- it searches like Folia: by name, by the text in documents, by what pictures show, with your tags, in your clouds and servers;
- it shows you what it found in a Folia tab, in the view you like (a list of exactly these files, or their folder with them selected);
- it arranges your windows: it saves scenes and workspaces you can open again any time;
- it proposes changes (create folders, move, copy, rename, tag, put in the Trash, compress, convert pictures…) in a Folia sheet: nothing happens before you validate, and you can untick any change or file;
- everything can be undone: nothing is ever overwritten (a name taken gets « 2 »), what is removed goes to the Trash, and each change is an operation of Operations signed with the agent's name, undone with ⌘Z;
- files that are online-only in iCloud Drive or another cloud are never downloaded for an agent.
It's off until you turn it on, in the welcome screens or in Settings › AI Agent / MCP.
Turn it on
- Open Settings › AI Agent / MCP.
- Turn on Allow AI agents to use Folia Files.
- Choose what agents may do:
| Level | What the agent can do |
|---|---|
| Help only | read Folia's documentation; it sees none of your files |
| Read and show | search your files, read their information (name, size, dates, tags; not their content), show them in a tab, save scenes and workspaces |
| Propose changes | all of that, and propose changes to files, which you validate in Folia |
Read the content of documents is a separate switch, off by default: with it, an agent can read the text of a PDF, a document or a picture (to summarise it, for instance). What an agent reads is sent to its AI provider.
Allowed Folders: agents see nothing else. By default your home folder (its Library stays hidden, except iCloud Drive and the clouds; so do the hidden files at its top) and the other disks and servers. Add or remove folders as you like.
Open Folia Files when an agent needs it: when Folia is closed, the agent opens it in the background.
Connect an agent
In Settings › AI Agent / MCP › Connect an Agent, choose your agent in the list: Folia explains how to connect it, step by step, with the button that does it. Claude, ChatGPT, Gemini and Grok come first (in the welcome screens too).
| Agent | How |
|---|---|
| Claude (the Mac app) | Install…: Claude asks to install the « Folia Files » extension; accept, then start a new conversation |
| ChatGPT (the Mac app) | Add to ChatGPT: Folia adds itself to ChatGPT's MCP servers with ChatGPT's own tool; quit ChatGPT and open it again |
| Gemini (the Mac app) | Copy Command, then in Gemini: Customize › Connectors › Custom, Local MCP tab: Server Name « Folia Files », Server ID « folia », paste the command in Command, then Connect. If Gemini can't reach Folia Files: Advanced Settings › Sandbox settings › Full Access. Google is opening the Local MCP tab gradually: if Gemini only asks for a link, your account can't launch Folia Files yet. |
| Grok | the Grok app only accepts online connectors: connect Grok Build, xAI's agent for Terminal. Copy Line, paste it in Terminal, then restart Grok Build |
| Claude Code | Copy Line, paste it in Terminal, then restart Claude Code |
| Codex | Copy Line, paste it in Terminal, then restart Codex |
| Cursor | Add to Cursor, then confirm in Cursor |
| VS Code | Add to VS Code, then confirm in VS Code |
| Another Agent | Copy Configuration and paste it in the agent's MCP settings (« mcpServers ») |
Every agent runs the same small program, folia-mcp, inside Folia Files (Folia Files.app/Contents/Helpers/folia-mcp). It talks to Folia on your Mac only: no network port, nothing reachable from another computer.
The first time an agent app uses Folia, Folia asks you: Allow or Decline. You can forget an app in Settings › AI Agent / MCP › Allowed Agents: it will ask again.
What you can ask
- « Tidy my Downloads folder: one folder per kind, and the duplicates to the Trash. »
- « Show me last year's invoices. »
- « Make a scene with my photo folders in Mosaic and the Map. »
- « What takes the space on my external disk? »
- « Compare these two folders before I delete the old one. »
- « Rename these scans with their date and the name of the shop. »
The proposal sheet
When an agent proposes changes, Folia comes forward with a sheet: the agent's name, its explanation, then each change with its files. Untick a change, or open it and untick some files; Show Files opens them in a tab first. Apply makes what is ticked; Decline makes nothing. The agent learns what was done, file by file.
A proposal waits 15 minutes for you; after that, it is dropped.
What agents did
Settings › AI Agent / MCP › What They Did lists the agents' last requests (in memory, until Folia quits). Their changes are also in Operations, with the agent's name, like any other.
Tools agents get
| Tool | Level |
|---|---|
search_docs, read_doc, list_docs: the documentation | Help only |
get_context (what you're looking at), list_folder, get_info, search_files, list_places, recent_items, recent_operations, get_shelf | Read and show |
show_files, open_folder, open_scene, open_workspace, create_scene, create_workspace, add_to_shelf | Read and show |
disk_usage, find_duplicates, compare_folders, mac_health, read_note, connect, open_tool | Read and show |
propose_changes, undo_operation, add_note, run_saved_job | Propose changes |
read_text | Read the content of documents |
open_tool fills in one of Folia's tools (batch actions on pictures and videos, PDF, batch rename, duplicates, compare) for you to check and run. run_saved_job runs one of your backups, syncs or rules, after you confirm.
Privacy
- What an agent sees of your files (names, folders, information, and text when you allowed it) is sent to the AI provider of that agent. Folia itself sends nothing anywhere.
- Agents only see the allowed folders, never your Library's private data, never the hidden files at the top of your home folder.
- Online-only cloud files are never downloaded for an agent.
Without the app: the documentation for any assistant
Folia's documentation is also an MCP server on the web, without an account: add https://foliafiles.com/mcp to your assistant (Claude: Settings › Connectors › Add custom connector) and ask it how to do something in Folia Files. It reads only this documentation.
If it doesn't work
The agent says why:
- « Access for AI agents is off »: turn it on in Settings › AI Agent / MCP.
- « Folia Files is not open »: open it, or turn on Open Folia Files when an agent needs it.
- « The user did not allow this app »: the app was refused; forget it in Allowed Agents and accept next time.
- « … is outside the folders Folia Files lets agents use »: add the folder in Allowed Folders.